Authentication

Every authenticated HTTP call sends one credential. Policies still decide what that caller may do.

For a normal call, send the API key from registration in x-api-key. Use the others only for the case they name:

• API key — the usual credential. On the Welcome page this is the API key; in the registration response it is rootApiKey.
• Session token — a short-lived stand-in for that key. Send it in x-token.
• Edge signature — the edge already has its own private key, before any owner exists. Sign nonce + timestamp with that key. This call creates the owner and returns rootApiKey, rootPublicKey, and rootPrivateKey.
• Request signature — after registration, sign nonce + timestamp + rootPublicKey with rootPrivateKey and send the public key with the call. The call then runs as that owner, instead of sending rootApiKey.

WebSocket delivery still authenticates with an API key or a session token on the connection. It does not use edge or request signatures.

API key#

Send the secret in x-api-key:

curl "https://api.bigstate.dev/v1/context" \
	--header "x-api-key: YOUR_API_KEY" \
	--header "Accept: application/json"

Session token#

Sign in returns token and expirationTime. Send that value in x-token until it expires, then revoke it or sign in again.

curl "https://api.bigstate.dev/v1/context" \
	--header "x-token: YOUR_TOKEN" \
	--header "Accept: application/json"

Signatures#

A signature is Ed25519 over a UTF-8 string. The signature value is uppercase hex. The private key is 64 hex characters (a 32-byte Ed25519 seed).

The signed string is nonce + timestamp. A request signature appends the public key: nonce + timestamp + publicKey.

The nonce is 7–13 alphanumeric characters. The timestamp is the current Unix time in seconds, as a decimal string. Use a new nonce and timestamp for each signed request.

Edge signature#

The edge signs with its own private key to register an owner. That key already exists; the owner does not. Sign nonce + timestamp. Do not append a public key.

• x-bs-edge-sign — uppercase hex signature
• x-bs-edge-sign-nonce — nonce
• x-bs-edge-sign-ts — Unix timestamp

The same three headers authenticate later calls that accept an edge signature.

Request signature#

Use the key pair registration just returned. Sign nonce + timestamp + rootPublicKey with rootPrivateKey. Send the signature and rootPublicKey together. The call runs as that owner.

• x-bs-sign — uppercase hex signature
• x-bs-sign-public-key — public key
• x-bs-sign-nonce — nonce
• x-bs-sign-ts — Unix timestamp

curl "https://api.bigstate.dev/v1/context" \
	--header "x-bs-sign: SIGNATURE" \
	--header "x-bs-sign-public-key: PUBLIC_KEY" \
	--header "x-bs-sign-nonce: NONCE" \
	--header "x-bs-sign-ts: TIMESTAMP" \
	--header "Accept: application/json"

Related#