Skip to main content
Production. This key signs OAuth2 id_tokens and the SSO client assertion.
See ADR-0010.

​
Prerequisites

  • HCP Terraform Cloud workspace (production / sandbox / test)
  • Render Dashboard to redeploy the API

​
1. Publish the new generation

In terraform/<environment>/aws.tf, add a generation named for the year and month. Leave the pointer alone.
Apply. The plan must create one aws_kms_key and update aws_iam_role_policy.signing in place, nothing replaced or destroyed — these keys carry no prevent_destroy.

​
2. Redeploy and check

An env group change does not redeploy services. Manual Deploy → Deploy latest reference on the API, then:
Both key ids must appear.

​
3. Wait a day

Merchants paste the JWKS URL into their own provider, and a cached set will not have the new key yet.

​
4. Move signing

Point current_generation at the new generation, apply, redeploy. kms:Sign follows it; the old key keeps kms:GetPublicKey.

​
5. Verify

Run an OAuth2 authorization-code flow: the id_token’s kid must be the new generation, and its signature must verify against the published set. Then an SSO login on a Private key JWT organization.

​
6. Wait seven days

Anything the old key signed expires within the hour but we keep a safety margin.

​
7. Retire it

Remove it from generations and apply. The plan must destroy that key and nothing else. KMS schedules the deletion 30 days out, cancellable until then.