48 lines
1.7 KiB
Markdown
48 lines
1.7 KiB
Markdown
# API docs
|
|
|
|
The API v1 interactive documentation is served by Django Ninja at `/api/v1/docs`.
|
|
|
|
What it provides:
|
|
- Swagger UI for all v1 routes, request/response schemas, and example payloads.
|
|
- Try-it-out support for GET/POST/PATCH/DELETE.
|
|
|
|
Authentication:
|
|
- Session auth works in the browser, but unsafe requests require CSRF.
|
|
- For API testing, use JWT: add `Authorization: Bearer <access_token>`.
|
|
|
|
Notes:
|
|
- Base URL for v1 endpoints is `/api/v1`.
|
|
- Admin-only routes return `403 Forbidden` when the token user is not staff/superuser.
|
|
|
|
Example: update server display name (admin-only)
|
|
|
|
PATCH `/api/v1/servers/{server_id}`
|
|
|
|
```json
|
|
{
|
|
"display_name": "Keywarden Prod"
|
|
}
|
|
```
|
|
|
|
## SSH user certificates (OpenSSH CA)
|
|
|
|
Keywarden signs user SSH keys with an OpenSSH certificate authority. The flow is:
|
|
- User uploads a public key (`POST /api/v1/keys`).
|
|
- Server signs the key using the active user CA.
|
|
- Certificate is stored server-side and can be downloaded by the user.
|
|
|
|
Endpoints:
|
|
- `POST /api/v1/keys/{key_id}/certificate` issues (or re-issues) a certificate.
|
|
- `GET /api/v1/keys/{key_id}/certificate` downloads the certificate.
|
|
- `GET /api/v1/keys/{key_id}/certificate.sha256` downloads a sha256 hash file.
|
|
|
|
Agent endpoints (mTLS):
|
|
- `GET /api/v1/agent/servers/{server_id}/ssh-ca` returns the CA public key for agent install.
|
|
- `GET /api/v1/agent/servers/{server_id}/accounts` returns account + system username (no raw keys).
|
|
|
|
Configuration:
|
|
- `KEYWARDEN_USER_CERT_VALIDITY_DAYS` controls certificate lifetime (default: 30 days).
|
|
- `KEYWARDEN_ACCOUNT_USERNAME_TEMPLATE` controls account name derivation.
|
|
|
|
Note: `ssh-keygen` must be available on the Keywarden server to sign certificates.
|