Skip to content

Keys and secrets

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).

A key is replaced after 90 days, without anyone doing anything:

  1. A day before, the next key is published in /jwks.json beside the current one, so that every verifier that caches the key set has it before it signs anything.
  2. Then it starts signing, and the old key is retired.
  3. 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).

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.

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.
  • 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 https addresses.
  • Where the deployment shares state between its servers (Redis), it shares only ids, hosts, hashes and counts: no tokens, codes, keys or user data.
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.