Skip to content
ChecktivChecktivChecktiv Docs

Secret key rotation

View as MarkdownOpen in ChatGPT(opens in new tab)Open in Claude(opens in new tab)

Your secret key (ah_sk_*) is what your backend uses to create sessions and mint bt_* browser tokens. Rotating it safely requires sequencing: deploy the new key before revoking the old one, because a revoked key fails session-mint requests immediately and strands any in-progress journeys.

For the console steps (generate a new key, copy it, revoke the old one), see API keys and Rotate and revoke API keys. This page covers the SDK-specific considerations.

Why sequencing matters for SDK integrations

Section titled “Why sequencing matters for SDK integrations”

When your backend uses ah_sk_* to call POST /v1/sessions/:id/browser_token, a revoked key returns 401 immediately. The SDK surfaces this as a token_expired error to the applicant mid-journey. Their session is stranded.

The safe order is:

  1. Generate the replacement key in the console and copy it immediately.
  2. Deploy your backend with the new key configured in your secrets manager.
  3. Verify that your mint endpoint is working with the new key (check logs for successful bt_* mints).
  4. Only then, revoke the old key in the console.

If your backend supports zero-downtime deploys, step 2 and 3 can happen with no interruption to active journeys.

If a key is compromised

Section titled “If a key is compromised”

Revoke immediately. A leaked ah_sk_* key can be used to mint unlimited billable sessions. Do not wait to stage a gradual rotation:

  1. Revoke the old key immediately in the console under Developers -> API keys -> [key] -> Revoke.
  2. Generate a replacement key and deploy it to your backend.
  3. Monitor your billing dashboard for unexpected session volume.

Journeys that are in-flight when the key is revoked will strand (the bt_* refresh will fail). Applicants affected by an emergency revocation will need to restart their verification.

Defense-in-depth: IP allowlist

Section titled “Defense-in-depth: IP allowlist”

If your mint backend has a fixed egress IP or CIDR range, you can optionally allowlist it on the secret key. A request from an IP outside the allowlist is rejected even with a valid key. This limits the damage from a leaked key to only traffic that originates from your expected egress.

Configure the CIDR allowlist when creating or editing a key in the console under Developers -> API keys.

Checking which key your backend is using

Section titled “Checking which key your backend is using”

Your backend should log the key prefix (the ah_sk_us_test_ or ah_sk_us_live_ prefix, not the full key) in its startup log so you can confirm which key is active in each environment without exposing the secret.

Section titled “Related pages”