# Bring your own key (BYOK)

With BYOK, secrets OhAuthCat stores (IdP client secrets, SP signing keys, social and Pipes credentials, Vault keys) are wrapped a second time with an AWS KMS key that you, or your customer, control. If the key is disabled or its grant removed, OhAuthCat can no longer open those secrets, and features that need them stop, failing closed.

## Scopes

- **Environment:** your key protects every secret of the environment.
- **Organization:** a customer's key protects that organization's connection secrets and Vault keys. Customers register it themselves in the setup portal through a portal link with the `encryption_keys` intent.

## Set up

1. `GET /v1/encryption_keys/setup` returns the AWS principal and the exact key policy statement to add to your KMS key.
2. `POST /v1/encryption_keys` with the `key_arn` (and `organization` for an organization key). OhAuthCat tests the key before accepting it; a bad key answers [`encryption_key_invalid`](/errors/encryption_key_invalid/), and a policy that grants more than needed answers [`encryption_key_policy_too_broad`](/errors/encryption_key_policy_too_broad/).
3. The new key becomes the active version, and a background job re-wraps existing secrets. `GET /v1/encryption_keys` shows each version's state (`active`, `enabled`, `deprecated`, `revoked`) and the re-wrap progress.

## Rotate and revoke

Register a new key ARN to rotate; the old version stays usable until the re-wrap finishes and you deprecate it with `POST /v1/encryption_keys/{key}/deprecate`. `activate` makes an older enabled version active again and `validate` tests one again. When KMS refuses OhAuthCat, every operation that needs that key fails with [`encryption_key_unavailable`](/errors/encryption_key_unavailable/).

Short-lived data (the brief sign-in fallback buffer, sandbox hand-offs and debug bundles) is not re-wrapped. BYOK is an Enterprise feature; the CLI can list key versions with `ohauthcat byok keys list`.
