Keys and secrets
Signing keys
Section titled “Signing keys”Each environment has its own signing keys, one of each algorithm:
| Algorithm | Signs |
|---|---|
| ES256 (P-256) | Every access token, and every ID token unless the client asked for RS256. |
| RS256 (RSA, 2048 bits) | The ID tokens of clients registered with id_token_alg: RS256. |
The public halves are published at the environment’s /jwks.json. The private halves never leave the service, and are stored encrypted (below).
Rotation
Section titled “Rotation”A key is replaced after 90 days, without anyone doing anything:
- A day before, the next key is published in
/jwks.jsonbeside the current one, so that every verifier that caches the key set has it before it signs anything. - Then it starts signing, and the old key is retired.
- A retired key stays published, and tokens it signed still verify, for another 24 hours. Then it is removed.
So the key set holds one key per algorithm most of the time, and two around a rotation. ES256 and RS256 rotate on their own schedules. Verifiers should pick the key by the token’s kid and fetch the key set again when they meet one they do not know, as the Rust SDK does.
An admin can start a rotation early, with Rotate the signing keys (POST /v1/environments/:id/keys/rotate): it publishes a next key, which starts signing 24 hours later. See Environments. Every rotation is recorded in the audit log (key.rotated).
The data key
Section titled “The data key”Each environment has a 32-byte data key of its own. It encrypts, with AES-256-GCM, every secret the service has to read back. The data key itself is stored wrapped (encrypted) by a key-encryption key that the deployment keeps apart from the database and its backups. Each encrypted value is bound to the row it belongs to, so a value copied to another row does not decrypt.
How each secret is stored
Section titled “How each secret is stored”| Secret | Stored as |
|---|---|
| Passwords | argon2id hashes (19 MiB of memory, 2 passes, 1 lane). |
| Refresh tokens, authorization codes, session cookies, login attempts, session tickets | SHA-256 hashes of 32 random bytes. |
| Email codes | SHA-256, salted with the login attempt. |
| Client secrets | SHA-256 hashes, compared in constant time. Shown once. |
| API keys | SHA-256 hashes. Shown once. |
| Recovery codes | HMAC-SHA256 under the data key. |
| Signing private keys | Encrypted under the data key. |
| Authenticator app (TOTP) secrets | Encrypted under the data key. |
| Webhook secrets | Encrypted under the data key. Shown once. |
| Social and custom provider client secrets | Encrypted under the data key. Never returned by the API. |
| An enrollment or a provider link in progress | Sealed (encrypted) under the data key into the token the browser carries, so nothing is stored until it completes. |
What leaves the service
Section titled “What leaves the service”- Tokens go only to the client they were issued to.
- Webhook deliveries carry the user’s id, email, name, picture and status, and the event’s data; never a token, a code or a password.
- Breached-password checks send the first five hexadecimal characters of the password’s SHA-1 hash, with padding.
- Custom providers and webhook endpoints are called only at public
httpsaddresses. - Where the deployment shares state between its servers (Redis), it shares only ids, hosts, hashes and counts: no tokens, codes, keys or user data.
If a secret leaks
Section titled “If a secret leaks”| Leaked | Do |
|---|---|
| A client secret | Rotate it (admin): the old one stops working at once. |
| An API key | Revoke it; create a new one. |
| A webhook secret | Roll it: the old one stops signing at once. |
| A user’s session | End it in Sessions, or all of the user’s sessions in Users. |
| Every session of an environment | End all sessions (admin, with the group’s slug as confirmation). See Sessions. |