Authentication & Signing
On this page 18 sections
- Choose a client implementation
- Required request headers
- Canonical message
- Signing procedure
- Subsequent requests
- Replay protection
- Verified upstream identity
- Public route exceptions
- Sending a prepared signed request
- Integration checks
- Identity auth endpoints
- POST /auth/login
- POST /auth/logout
- GET /auth/status
- GET /auth/federation
- GET /api/identity/status
- GET /api/identity/federated-binding
- Handle session transitions
This HTTP signing contract applies to browser, native and server-to-server clients. JSON bodies and HTTP headers below are wire formats, not JavaScript code. Use your language’s HTTP client and Ed25519 implementation for custom clients; keep private keys in storage appropriate to that client.
Choose a client implementation
The qscs-bootstrap package supplies the browser signer and matching WASM. Core serves these files and injects its client into eligible HTML pages when Browser navigation is enabled. These helpers run in the browser and do not require a JavaScript backend. Use qscs.fetch for explicit signed requests and qscs.createSession for authentication. The integration guide covers application setup. The formats below support custom clients.
Required request headers
| Header | Format |
|---|---|
X-QSCS-Client-Uuid | 32 lowercase hex characters identifying the client key binding. |
X-QSCS-Ts | Decimal Unix milliseconds, within ±60,000 ms of the node clock. |
X-QSCS-Nonce | 16 fresh random bytes encoded as 32 lowercase hex characters. |
X-QSCS-Sig | Standard base64 of the 64-byte Ed25519 signature, including padding. |
Canonical message
METHOD + LF + HOST + LF + URI + LF + BODY + LF + TS_MS + LF + NONCE_HEX
Concatenate the raw bytes with one LF byte between fields and no trailing LF. The method is uppercase. HOST is the destination hostname without its port. URI is the transmitted path and query string. BODY is the exact transmitted body, empty when absent. Do not decode the URI, reorder its query, hash the body or serialize JSON again after signing. Timestamp and nonce must match their headers.
Signing procedure
- Create a client identifier and Ed25519 keypair using a cryptographic random generator. Keep the private key on the client.
- Serialize the exact body bytes once. For JSON, keep that serialization unchanged through sending.
- Choose the destination hostname and exact path/query that Core will receive. Generate the timestamp and a fresh random nonce.
- Build the canonical byte sequence and sign it with Ed25519. Encode the signature as standard base64.
- Send the original body and the four matching headers. Regenerate proof for every attempt and for every changed target.
Canonical-byte layout — empty GET body; illustrative timestamp/nonce, no trailing LF
GET
api.example.com
/api/report?range=7d
1792790400000
000102030405060708090a0b0c0d0e0f
The example timestamp and nonce are not reusable credentials. Use current time and fresh randomness in real requests. Native clients can use any compatible HTTP/Ed25519 libraries; browser clients use the packaged signer.
Subsequent requests
Protected requests use the registered UUID and private key. The gate looks up the public key for the request origin and verifies the signature, timestamp and nonce. Invalid or unknown identities receive HTTP 401. Public bootstrap paths and static assets have explicit gate exemptions; keep sensitive APIs outside them.
Replay protection
Use a fresh nonce and current timestamp for every attempt, including retries. The serving node rejects nonce reuse within its bounded in-memory replay window and timestamps outside ±60 seconds. This replay tracking is node-local and is not an application-wide idempotency store. Keep clocks synchronized. A captured signature is bound to its method, host, URI and body; it cannot be reused to authorize a different request.
Verified upstream identity
X-QSCS-Identity: <32-hex client UUID>
X-QSCS-Authenticated-Subject: account:42
X-QSCS-Identity-Issuer: app.example.com
QSCS strips incoming copies before adding verified values. The backend must only trust them through its restricted QSCS ingress, check the issuer and apply its own account and permission checks. Do not expose a direct public route that accepts these headers.
Public route exceptions
On an Auth=identity origin, the current gate permits GET/HEAD for the root; paths ending in .css, .js, .svg, .ico, .json, .woff2 or .wasm; and paths beginning /css/, /js/, /static/, /favicon or /.well-known/. Matching configured static files can also mark a path public. Exact packaged runtime paths are handled before the gate. Do not place private JSON APIs under an exempt extension or prefix.
The /auth/ namespace bypasses the generic gate, with login/logout enforcing their own proof. Keep it reserved. Legacy POST requests to / with a leading api query parameter for register, forgot-password, verify-email, reset-password, resend-verification or request-password-change also bypass the generic gate and require backend validation. Explicit monitoring-ingress paths use their own backend node authentication. These exceptions do not make arbitrary application routes public.
Sending a prepared signed request
For a non-browser client, build and sign the canonical bytes using an Ed25519 implementation. The following shell/curl example sends an already prepared signature; curl does not calculate it. body.json must contain exactly the bytes used to produce the signature.
curl --request POST "https://${HOST}/auth/login" \
--header 'Content-Type: application/json' \
--header "X-QSCS-Client-Uuid: ${UUID}" \
--header "X-QSCS-Ts: ${TS_MS}" \
--header "X-QSCS-Nonce: ${NONCE_HEX}" \
--header "X-QSCS-Sig: ${SIG_BASE64}" \
--data-binary @body.json
Integration checks
| Check | Expected configuration |
|---|---|
| Host and target | Preserve the public hostname, path and query through the proxy. |
| Body | Sign the same bytes that are transmitted. |
| Clock and nonce | Use milliseconds and a fresh nonce for every request. |
| Identity readiness | Await readiness before reading the UUID or key. |
| Authentication result | Check JSON ok on login and logout. |
| Backend trust | Accept verified identity headers only through trusted QSCS ingress. |
Identity auth endpoints
These endpoints establish, inspect and revoke an origin-scoped client identity over HTTP/JSON, independently of backend or client language. For browser applications, use the packaged qscs.createSession controller for sign-in, restoration and logout. It supplies identity values and signatures automatically. The wire formats below are for custom integrations. The integration guide includes the complete browser flow.
POST /auth/login
Authentication: proof of possession using the key supplied in the body, plus account credentials validated by the configured authority. Content-Type: application/json. Use this exact path without a query or trailing slash.
| Field | Type | Required / meaning |
|---|---|---|
| username | string | Required; non-empty account login name. Custom verifier credentials use the first colon as separator, so do not include a colon in the username. |
| password | string | Required; non-empty credential sent to the configured authority. Use HTTPS. |
| client_uuid | string | Required; client-generated identifier. Use 32 lowercase hex characters and the same value in the UUID header. |
| pubkey | string | Required; 32-byte Ed25519 public key encoded as 64 hex characters. Never send the private key. |
The body contains username, password, client_uuid (32 hex) and pubkey (64 hex). Sign it using the matching private key and the four headers described in Authentication & Signing. The node verifies proof of possession, validates credentials with the configured authority, stores the binding and replicates it to peers.
{"username":"alice","password":"...","client_uuid":"<32 hex>","pubkey":"<64 hex>"}
HTTP 200 JSON — successful login:
{"ok":true,"uuid":"<32 hex>","origin":"app.example.com"}
Check ok rather than HTTP status alone. A rejected login can return HTTP 200 with ok:false and an error describing an invalid request, rejected credentials or unavailable authority. After login succeeds, verify a signed read of your application’s account endpoint before starting other private requests. Retry a short issuer-binding propagation delay using fresh signed GETs; do not replay the login POST. See the packaged session controller.
| error value | Meaning |
|---|---|
| invalid login JSON | Body could not be parsed. |
| missing required fields: username, password, client_uuid, pubkey | One or more required string fields are absent or empty. |
| invalid pubkey length / malformed pubkey | Public key encoding is invalid. |
| signature invalid | Request proof, timestamp or nonce validation failed. |
| authentication failed | Authority rejected credentials. |
| control plane unreachable | Control-plane authentication authority could not be reached. |
| auth endpoint unreachable | Custom IdentityAuthUrl could not be reached. |
| identity auth misconfigured | Custom verifier URL is invalid. |
| custom auth requires HTTPS or loopback HTTP | Custom verifier URL uses disallowed plaintext transport. |
| identity auth not configured | Required identity service is unavailable. |
| authentication response missing subject | Authority did not return the safe account subject required by federation. |
These failures return HTTP 200 with {"ok":false,"error":"…"}. Never log submitted passwords. Additional configuration-specific error strings can occur.
POST /auth/logout
Authentication: existing origin key. Use the exact path without a query or trailing slash. The handler returns HTTP 200 JSON for both success and failure. Send an empty signed body with the current client UUID. QSCS verifies against the stored key, removes the origin binding and propagates revocation. Check JSON ok:true before rotating the local identity. Preserve the key to retry if sign-out is not confirmed.
{"ok":true,"erased":true}
An already absent binding can return {"ok":true,"erased":false}. An invalid signature for an existing binding returns ok:false. Allow for revocation propagation across peers and federated recipients. Failure responses use {"ok":false,"error":"…"} with identity store not configured, missing client identity or signature invalid.
GET /auth/status
Request parameter: X-QSCS-Client-Uuid header. Scope: UUID plus request Host. Response: HTTP 200 JSON with ETag, or 304 with no body when If-None-Match matches. A missing UUID or absent binding returns authenticated:false.
Returns the binding status for X-QSCS-Client-Uuid and the request host. This lookup does not require a request signature. The browser SDK supplies its cached UUID; await its readiness first to check the persisted identity. Custom clients supply their own stored client UUID. This is a UI hint, not proof that a caller possesses the private key.
JSON — binding present:
{"authenticated":true,"username":"account:42","uuid":"<32 hex>"}
JSON — no authenticated binding:
{"authenticated":false}
The legacy field name username carries the stored subject when the authority supplies one. Use verified upstream identity and application account checks for authorization.
GET /auth/federation
Authentication: none. No request body or query required. Discovery is scoped to the issuer Host. Returns HTTP 200 application/json with Cache-Control: no-store.
JSON response example
{"managed":true,"recipients":[{"origin":"https://api.example.com","paths":["/api/reports/"]}]}
| Field | Type | Meaning |
|---|---|---|
| managed | boolean | Whether console-managed federation is active. |
| recipients | array | Managed recipient entries for this issuer; can be empty. |
| recipients[].origin | string | HTTPS recipient origin. |
| recipients[].paths | array of strings | Permitted path prefixes. |
Discovery does not grant access. In standalone deployments the managed recipient list may be empty; use the configured audience/trust relationship. Sign recipient requests against their destination Host and exact URI, including __qscs_issuer when supplied.
Shell / curl — public discovery
curl -i 'https://app.example.com/auth/federation'
GET /api/identity/status
A diagnostic lookup by the required ?uuid=<32 hex> query parameter. HTTP 200 is used for found, unknown and error results. It searches this node’s local store by UUID, not by UUID plus the request Host, and reports the first matching record’s origin and recorded timestamp. It is not an authorization proof and must not be used to grant application access.
{
"uuid": "<32 hex>",
"authenticated": true,
"origin": "app.example.com",
"last_seen": 1792790400000,
"found": true
}
The current writer stores last_seen as Unix milliseconds at binding creation; it is not a live visitor-activity counter. Older persisted records can contain seconds. A missing UUID returns {"error":"missing required parameter: uuid"}; an unknown identity returns authenticated:false and found:false, without origin or last_seen.
GET /api/identity/federated-binding
Advanced issuer-to-recipient lookup, normally called by QSCS nodes. Application clients should send their signed request to the recipient API instead. Query parameter: audience, the recipient hostname. The issuer requires an explicitly allowed recipient and path.
| Header | Value |
|---|---|
| X-QSCS-Federation-Method | GET; other target methods are rejected by this lookup. |
| X-QSCS-Federation-Host | Recipient hostname; must equal audience. |
| X-QSCS-Federation-Uri | Original recipient path and query. |
| X-QSCS-Client-Uuid, X-QSCS-Ts, X-QSCS-Nonce, X-QSCS-Sig | Original recipient-bound proof. Sign the recipient GET with an empty body, not the issuer lookup URL. |
JSON — accepted binding, HTTP 200
{"authenticated":true,"uuid":"<32 hex>","issuer":"app.example.com","subject":"account:42","pubkey":"<64 hex>"}
An invalid target, disallowed path, missing binding or invalid proof returns HTTP 200 with {"authenticated":false}. The issuer verifies proof without consuming the recipient’s replay nonce; the recipient still verifies and consumes it for the protected request.
Handle session transitions
Serialize login and logout, cancel old requests, and clear account-specific client state, private UI where present, and delta baselines on account changes. Persist pending logout before sending it; after reload, finish pending revocation before restoring a session. Keep the old key until logout is confirmed, then rotate.
If a federated API returns 401 or 403, verify the protected account endpoint at the issuer before ending the session. While that account remains valid, retry a recipient 401 with bounded GET-only backoff and fresh signatures; show a recipient 403 as a resource denial. A timeout or 5xx is a service error, not proof of logout. See the response-handling recipe.
See Configuring Gated Identity for deployment and application setup.