keywarden/API_DOCS.md

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}

{
  "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.