Skip to content
Dashboard
Theme
Theme

Bring your own key (BYOK)

Protect every secret OhAuthCat holds for an environment or organization with your own AWS KMS key, with rotation and immediate revocation.

View Markdown

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.

  • 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.
  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, and a policy that grants more than needed answers 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.

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.

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.