Authentication and security

Two local credentials, two jobs

Bootstrap sequence

1. 01
   Receive

   The local process constructs the launch URL or passes a launch token to its interface. Treat the token as a secret.

2. 02
   Exchange

   POST {baseUrl}/api/session/exchange with {launchToken}. The token is one-use and expires after five minutes.

3. 03
   Attach

   Send X-OpenSS-Session on every protected API request.

4. 04
   Expire

   Local session tokens are valid for eight hours or until the engine shuts down and invalidates them.

Required headers

X-OpenSS-Session: <session-token>
X-OpenSS-Account-Token: <account-token>  # hosted AI, Pro context or provider-key routes
Content-Type: application/json

Account-backed routes

Hosted AI at POST /api/hosted-ai/respond requires X-OpenSS-Account-Token and forwards it to the OpenSS account backend. Provider-key routes and persistent chat context perform their own Pro entitlement checks. The local API does not mint, refresh or reveal account credentials.

Origin and network boundary

• The engine accepts only 127.0.0.1 binding; run_gui rejects another host.
• CORS allows the engine origin and explicitly configured packaged origins, not arbitrary websites.
• API requests with an unapproved Origin or Referer receive INVALID_ORIGIN.
• Request bodies are capped at 12 MiB. Captured image bytes are capped at 6 MiB and must be valid PNG, JPEG or WebP data.
• OpenAPI, Swagger UI and ReDoc are disabled. The documented contract is intentionally curated instead of discoverable through a public schema.

Safe client behavior

const response = await fetch(baseUrl + "/api/version");

// Keep tokens outside URLs, logs and persisted browser storage.
const sessionToken = exchange.sessionToken;
const headers = { "X-OpenSS-Session": sessionToken };