HTTP API

The API is what the served UI and the shells speak; it is documented here for people writing their own client or automation. FastAPI also publishes an OpenAPI description at /openapi.json and an interactive explorer at /docs on the API port, but neither can be used directly because of the encryption envelope described first.

Conventions

Base URL. https://<server>:8443 (through Caddy) or http://<server>:8000 (the API server directly). Both serve the same routes.

Handshake. Before anything else, establish a crypto session:

POST /api/handshake/initiate         -> {"nonce": b64, "signature": b64}
   verify: RSA-PSS(SHA-256, salt 32) over the nonce with the server public key
POST /api/handshake/exchange         {"encrypted_session_key": b64}
   RSA-OAEP(SHA-256) of a 32-byte AES key under the server public key
                                     -> {"session_id": hex}

Envelope. Every endpoint marked encrypted below expects the header X-Session-ID: <session_id> and, for requests with a body, {"iv": b64, "ciphertext": b64} where the ciphertext is AES-256-GCM of the JSON body with a 12-byte IV and no additional data. JSON responses come back in the same envelope. Optionally add X-Idempotency-Key: <random> to a non-GET request to make a retry safe.

Authentication. Endpoints marked user or admin require Authorization: Bearer <jwt>, an RS256 token signed with the user's private key whose claims include sub (the username) and exp. admin endpoints additionally require an administrator account.

Errors. Standard HTTP status codes with a JSON {"detail": ...} body: 400 for a bad envelope or crypto session, 401 for a bad token, 403 for a permission the account lacks, 404, 422 for a body that fails validation, 500 for provider errors.

Handshake and status

Applications and launching

A launch returns {"session_url", "session_id"}; session_url is relative to the session port and contains the one-time access token.

Sessions

Everything under /{session_id}/ other than the initial exchange is proxied by Caddy to the container after forward_auth.

Home directories

Uploads

Uploads are chunked so that large files fit within the encrypted envelope. Upload ids are lowercase UUIDs scoped to the uploading user.

Files

All paths are relative to the named home directory (or _sealskin_shared_files).

Public shares

Administration

All encrypted, admin.

Internal

GET /internal/resolve_session/{session_id} exists only for Caddy's forward_auth; Caddy refuses it on the public listener and the API server only receives it over loopback. It answers 200 with X-Upstream-Host and X-Upstream-Auth headers, or 403/404.