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.

ConventionsCopy Anchor Link

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), exp, and sid, the X-Session-ID it is sent with (a token without sid is refused on the API port itself and taken only through the node's TLS proxy), or, on the plain lane, Authorization: Bearer ssk_<id>_<secret>, an application key with the client's name in X-SealSkin-App (chrome, firefox, android, ios, else other). A refused key answers 401 with the code in detail: unknown, expired, disabled, client, or dormant. The companion apps call every endpoint under /companion/, as /companion/api/..., where a key is the one credential taken. admin endpoints additionally require an administrator account.

The plain lane. A request through Caddy that names no crypto session is taken and answered as plain JSON, with no envelope: it is how the web app, the companion apps with an application key, and the nodes of a cluster call every endpoint below. It authenticates with the cookie of a web sign-in or the header of a trusted proxy, both of which are honored only on a request the browser marks as coming from the web app's own pages (Sec-Fetch-Site: same-origin, else a matching Origin), with an application key, or with another node's signature. 409 answers a write another node got in ahead of, and 503 one the shared store could not take.

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 statusCopy Anchor Link

Web sign-inCopy Anchor Link

The provider's callbacks and logout notices (/api/auth/oidc/callback, /api/auth/oidc/backchannel-logout, /api/auth/oidc/frontchannel-logout, /api/auth/saml/acs, /api/auth/saml/slo) are for the provider.

Application keysCopy Anchor Link

The user's own routes answer a web sign-in alone, the cookie's or the proxy's: a key, or a key-file client, cannot manage keys.

Applications and launchingCopy Anchor Link

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

SessionsCopy Anchor Link

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

Home directoriesCopy Anchor Link

UploadsCopy Anchor Link

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

FilesCopy Anchor Link

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

Public sharesCopy Anchor Link

AdministrationCopy Anchor Link

All encrypted, admin.

BrandingCopy Anchor Link

Every page the server serves carries the brand in its head: an application-name meta, a sealskin-brand meta holding the name, logo address, logo link, accent, and store-links switch as JSON, and a style rule deriving the accent palette.

ClusterCopy Anchor Link

A launch request may name a pool or a node to start on. A request about a session or a home directory on another node is forwarded there and answered with that node's answer.

InternalCopy Anchor Link

GET /internal/resolve_session/{session_id} and GET /internal/route/{session_id} exist only for Caddy's forward_auth; Caddy refuses them on its listeners and the API server only receives them over loopback. The first answers 200 with X-Upstream-Host and X-Upstream-Auth headers, or with X-Upstream-Peer for a session another node runs, or 403/404; the second answers only whether another node runs the session.

/peer/* is what nodes call on each other's peer listener, each request signed with the calling node's server key: status, change notices, joining, the shared records of a node that keeps them, uploads a frontend passes on, home directories being moved, and the storage of a user a frontend deleted.