REST API Reference

This document provides an exhaustive reference for every HTTP endpoint implemented in apps/api.

---

Access & Security Categories

Category	Transport / Auth	CORS Policy	Scope / Target
Public Protocol	None or Basic/Bearer	* (Wildcard Open)	OIDC discovery, JWKS, token exchanges, and host KRL sync
Dashboard Session	HttpOnly session cookie	Explicit dashboard origin only	Protected operations driven by the React management console
Administrative	Session + RBAC permission	Explicit dashboard origin only	Operator and superadministrator endpoints (/api/admin/*)

---

1. OpenSSH Certificate Authority & Host Sync

GET /api/ssh/ca/pubkey

GET Public

Returns the raw OpenSSH CA public key line for target host trust configuration.

• Request Headers: None
• Response: 200 OK (text/plain; charset=utf-8)

  ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGfX04J5k0FvC78sT5M0tD94YvF5Jg... ca@id.example.com

• Host Integration: Written directly to /etc/ssh/trusted_user_ca.pub on target Linux servers.

---

GET /api/ssh/ca/revoked-keys

GET Public

Outputs the dynamic Key Revocation List (KRL).

• Query Parameters:

  Parameter	Type	Required	Description
  format	string	No	krl (or binary) for native OpenSSH PROTOCOL.krl binary wire format; raw for newline-delimited serials (serial: <id>); default is JSON.
  includeExpired	boolean	No	Set to true to include expired revoked certificates alongside unexpired certificates.
  wildcard	boolean	No	When format=krl, set to true to omit the CA public key and apply revocations as wildcard CA.

• Headers:

  Header	Description
  Accept: application/octet-stream	Automatically selects binary KRL format if format is unspecified.

• Responses:
  • format=krl: 200 OK (application/octet-stream) binary OpenSSH KRL file
  • format=raw: 200 OK (text/plain; charset=utf-8)

    serial: 117284521030851699
    serial: 117284521030851700

  • Default: 200 OK (application/json)

    {
      "revoked": [
        { "serial": "117284521030851699", "revokedAt": 1726588800 }
      ]
    }

• Host Integration: Synchronized periodically by ssh-revoked-keys.service to update /etc/ssh/revoked_keys.

---

2. OAuth 2.0 & OpenID Connect Core

GET /.well-known/openid-configuration

GET Public

Returns the RFC 8414 / OpenID Connect Discovery document.

• Response: 200 OK (application/json)

  {
    "issuer": "https://id-api.example.com",
    "authorization_endpoint": "https://id-api.example.com/oauth/authorize",
    "token_endpoint": "https://id-api.example.com/oauth/token",
    "userinfo_endpoint": "https://id-api.example.com/oauth/userinfo",
    "jwks_uri": "https://id-api.example.com/.well-known/jwks.json",
    "revocation_endpoint": "https://id-api.example.com/oauth/revoke",
    "introspection_endpoint": "https://id-api.example.com/oauth/introspect",
    "response_types_supported": ["code"],
    "subject_types_supported": ["public"],
    "id_token_signing_alg_values_supported": ["ES256"],
    "scopes_supported": ["openid", "profile", "email", "offline_access"],
    "token_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic", "none"],
    "code_challenge_methods_supported": ["S256"]
  }

---

GET /.well-known/jwks.json

GET Public

Returns the JSON Web Key Set containing the active ECDSA P-256 public signing key. (Aliased at /.well-known/jwks).

• Response: 200 OK (application/json)

  {
    "keys": [
      {
        "kty": "EC",
        "crv": "P-256",
        "alg": "ES256",
        "use": "sig",
        "kid": "Muljax-id-1",
        "x": "W4o3L8yv4N0jA8m-sR9Q7x1z2...",
        "y": "K9p2M1n0B7v6C5x4Z3a2S1d0..."
      }
    ]
  }

---

POST /oauth/token

POST Public (Client Auth)

Exchanges an authorization code, refresh token, or client credentials for tokens.

• Content-Type: application/x-www-form-urlencoded
• Request Parameters:

  Parameter	Type	Required	Description
  grant_type	string	Yes	authorization_code, refresh_token, or client_credentials.
  client_id	string	Yes	Registered OAuth client identifier.
  client_secret	string	Confidential	Client secret for confidential clients.
  code	string	Code Grant	Authorization code (ac_...).
  redirect_uri	string	Code Grant	Redirect URI exactly matching the authorization request.
  code_verifier	string	Code Grant	Raw PKCE verifier (43–128 characters).
  refresh_token	string	Refresh Grant	Refresh token (rt_...).

• Response: 200 OK (application/json)

  {
    "access_token": "at_9b2e04f128c701d4",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "rt_81f09c88210e4a7b",
    "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6Ik11bGpheC1pZC0xIn0...",
    "scope": "openid profile email offline_access"
  }

---

GET /oauth/userinfo

GET Bearer Token

Returns OpenID Connect claims for the authenticated subject.

• Request Headers: Authorization: Bearer <access_token>
• Response: 200 OK (application/json)

  {
    "sub": "usr_01HXYZ123456789ABCDEF",
    "email": "alice@example.com",
    "email_verified": true,
    "name": "Alice Smith",
    "given_name": "Alice",
    "family_name": "Smith",
    "preferred_username": "alice"
  }

---

POST /oauth/revoke

POST Public (Client Auth)

Revokes an issued token per RFC 7009.

• Parameters: token (string), token_type_hint (optional: access_token or refresh_token).
• Response: 200 OK ({ success: true }).

---

POST /oauth/introspect

POST Public (Client Auth)

Inspects token status per RFC 7662.

• Parameters: token (string).
• Response: 200 OK ({ active: true, scope: "openid", client_id: "...", exp: 1773756000 }).

---

3. Session & Authentication Endpoints (/api/auth)

Protected by dashboardCors(). Uses HttpOnly session cookies.

Endpoint	Method	Description	Request Body	Response
/api/auth/register	POST	Create a new user account	{ email, password, displayName? }	201 Created + Session Cookie
/api/auth/login	POST	Authenticate with password	{ email, password, rememberMe? }	200 OK + Session Cookie
/api/auth/logout	POST	Invalidate current session	None	200 OK + Clears Cookie
/api/auth/me	GET	Resolve active session user	None	{ user, session, roles, permissions }
/api/auth/sessions	GET	List active sessions	None	{ sessions: Session[] }
/api/auth/sessions/:id/revoke	POST	Invalidate specific session	None	{ success: true }
/api/auth/sessions/revoke-all	POST	Invalidate all other sessions	None	{ success: true }
/api/auth/password-reset	POST	Request password reset token	{ email }	200 OK

---

4. WebAuthn & Passkeys (/api/passkeys)

Endpoint	Method	Auth	Description	Payload / Response
/api/passkeys/register/options	POST	Session	Generate WebAuthn creation options	Returns PublicKeyCredentialCreationOptionsJSON
/api/passkeys/register/verify	POST	Session	Verify attestation & save passkey	Body: { response, name? }
/api/passkeys/login/options	POST	Public	Generate userless assertion challenge	Returns { challengeId, ...options }
/api/passkeys/login/verify	POST	Public	Verify assertion & issue session cookie	Body: { response, challengeId }
/api/passkeys	GET	Session	List registered authenticators	Returns { passkeys: Passkey[] }
/api/passkeys/:id	PATCH	Session	Rename authenticator	Body: { name: string }
/api/passkeys/:id	DELETE	Session	Delete authenticator credential	Returns { success: true }

---

5. Account Self-Service (/api/account)

Endpoint	Method	Auth	Description	Payload / Response
/api/account/profile	GET	Session	Get user profile attributes	Returns profile claim object
/api/account/profile	PATCH	Session	Update profile attributes	Body: { displayName?, preferredUsername?, ... }
/api/account/profile/avatar	GET	Public/Session	Serve user avatar image	Binary image stream from R2
/api/account/profile/avatar	PUT	Session	Upload user avatar	multipart/form-data with file
/api/account/profile/avatar	DELETE	Session	Delete user avatar	Returns { success: true }
/api/account/password	POST	Session	Update password	Body: { currentPassword, newPassword }
/api/account/oauth/grants	GET	Session	List authorized third-party apps	Returns { grants: OAuthGrant[] }
/api/account/oauth/grants/:clientId	DELETE	Session	Revoke third-party access	Returns { success: true }

---

6. SSH Keys & User Certificates (/api/ssh)

Endpoint	Method	Required Permission	Description	Request / Response
/api/ssh/keys	GET	ssh:keys:manage	List registered Ed25519 public keys	Returns { keys: UserSshKey[] }
/api/ssh/keys	POST	ssh:keys:manage	Register an Ed25519 public key	Body: { name, publicKey }
/api/ssh/keys/:id	DELETE	ssh:keys:manage	Remove registered public key	Returns { success: true }
/api/ssh/principals	GET	ssh:cert:issue	List authorized UNIX principals	Returns { principals: string[] }
/api/ssh/certs/issue	POST	ssh:cert:issue	Mint signed OpenSSH certificate	Body: { savedKeyId, ttlSeconds? }
/api/ssh/certs	GET	ssh:cert:list	Audit log of all issued certs	Returns { certificates: SshCert[] }
/api/ssh/certs/:id/revoke	POST	ssh:cert:revoke	Revoke certificate & update KRL	Body: { reason? }

---

7. Administrative Operations (/api/admin)

Requires admin role or specific permission flags.

User Management

• GET /api/admin/users: List users (users:read).
• POST /api/admin/users: Create user account (users:write).
• GET /api/admin/users/:userId: Get user account details (users:read).
• PATCH /api/admin/users/:userId: Update user account attributes (users:write).
• DELETE /api/admin/users/:userId: Delete user account (users:delete).
• POST /api/admin/users/:userId/lifecycle: Enable, disable, or schedule action (users:lifecycle).
  • Request: { action: "enable" | "disable", executeAt?: number }.

Roles & Permissions

• GET /api/admin/roles: List all roles (roles:read).
• POST /api/admin/roles: Create custom role (roles:write).
• PATCH /api/admin/roles/:id: Update role metadata (roles:write).
• DELETE /api/admin/roles/:id: Delete custom role (roles:write).
• GET /api/admin/roles/:id/permissions: View permissions granted to role (roles:read).
• POST /api/admin/roles/:id/permissions: Grant permission to role (roles:write).
• DELETE /api/admin/roles/:id/permissions/:permissionId: Revoke permission from role (roles:write).
• GET /api/admin/permissions: View system permissions catalog (permissions:read).

User Role Assignments

• GET /api/admin/users/:userId/roles: List roles assigned to user (roles:read).
• POST /api/admin/users/:userId/roles: Assign role (roles:assign, Body: { roleId }).
• DELETE /api/admin/users/:userId/roles/:roleId: Remove role (roles:assign).

Superadmin Bootstrap

• POST /api/admin/bootstrap: One-time administrative elevation with ADMIN_BOOTSTRAP_SECRET.
  • Body: { secret: string }.

---

8. OAuth Client Management (/oauth/clients)

Endpoint	Method	Permission	Description
/oauth/clients	GET	oauth_clients:read	List all registered applications
/oauth/clients	POST	oauth_clients:write	Register new application ({ name, clientType, redirectUris, scopes })
/oauth/clients/:clientId	PATCH	oauth_clients:write	Update client name, redirect URIs, or scopes
/oauth/clients/:clientId	DELETE	oauth_clients:write	Delete application and cascade revoke all issued tokens
/oauth/details	GET	Session	Retrieve client name & scopes for consent prompt
/oauth/approve	POST	Session	Approve user consent grant

---

9. Real-Time Notifications (/api/notifications)

Endpoint	Method	Description
GET /api/notifications	GET	List notifications for authenticated subject
GET /api/notifications/stream	GET	Persistent Server-Sent Events (SSE) notification stream
PATCH /api/notifications/:id/read	PATCH	Mark individual notification as read
POST /api/notifications/read-all	POST	Mark all notifications as read