Guides

BYOK (bring your own keys)

Hold the keys to your own identity data. With bring-your-own-keys, OrthID encrypts sensitive records with a key you own in Vault, AWS KMS, or an HSM, so the data is unreadable without your authorisation.

OrthID encrypts sensitive fields at the application layer before they ever reach Postgres. By default it manages the encryption key for you. With BYOK, that key (the key-encryption key, or KEK) lives in your own key provider instead. OrthID calls your provider to wrap and unwrap data-encryption keys, but it never holds the KEK itself. Revoke OrthID’s access in your provider and the data goes dark, even to us.

BYOK is part of the sovereignty model. Pairing customer-managed keys with a pinned region means your identity data is both stored and decryptable only inside a boundary you control. See Regions & sovereignty for how the two fit together.

How it works

OrthID uses envelope encryption. Each sensitive record is encrypted with a per-record data-encryption key (DEK). The DEK is then wrapped by your KEK in your provider. To read a record, OrthID asks your provider to unwrap the DEK; your provider authorises (or denies) the call and logs it. The KEK material never leaves your provider.

Configure a key provider

Set ORTHID_SECRETS_PROVIDER to vault, aws-kms, or hsm, then point OrthID at the key. The examples below show Vault Transit and AWS KMS. An HSM uses the same shape over PKCS#11 with a pkcs11:// key URI.

orthid.yaml

secrets:
  # ---- Option A: HashiCorp Vault (Transit engine) ----
  provider: vault
  vault:
    address: https://vault.internal:8200
    # OrthID authenticates with its own Kubernetes service account.
    authMethod: kubernetes
    role: orthid
    # The Transit key used to wrap/unwrap data-encryption keys.
    transitKey: orthid-kek

  # ---- Option B: AWS KMS ----
  # provider: aws-kms
  # awsKms:
  #   keyArn: arn:aws:kms:ap-southeast-2:123456789012:key/abcd-1234
  #   region: ap-southeast-2

  # ---- Option C: PKCS#11 HSM ----
  # provider: hsm
  # hsm:
  #   keyUri: pkcs11:token=orthid;object=kek;type=secret-key

Your provider must allow the OrthID identity (the Vault role, the KMS key policy principal, or the HSM slot user) to perform wrap and unwrap (in KMS terms, Encrypt and Decrypt) on that key, and nothing more. OrthID never needs to export or delete the key.

Key rotation

Rotate the KEK in your provider on whatever schedule your policy requires. OrthID supports rotation without re-encrypting every record up front: new data is wrapped with the new key version immediately, and existing records are re-wrapped lazily on next access or by a background job you can trigger on demand.

Terminal

# 1. Rotate the key version in your provider.
vault write -f transit/keys/orthid-kek/rotate

# 2. Tell OrthID to adopt the new version for all new writes.
orthid keys rotate --provider vault

# 3. (Optional) Re-wrap existing DEKs in the background to the latest version.
orthid keys rewrap --batch 500

Keep old key versions until rewrap completes

Rotation creates a new key version but does not delete old ones. Records wrapped with a previous version still need it to unwrap. Do not disable or destroy an old KEK version until orthid keys rewrap has finished and reports zero records on prior versions, or those records become permanently unreadable.

What your keys protect

BYOK encrypts the data that identifies and authenticates an actor. The following is wrapped with your KEK and is unreadable if you revoke access:

User profile fields: email, phone, name, and any custom attributes.
Authentication factors: passkey credentials, TOTP seeds, and recovery codes.
SSO and SCIM connection secrets, and stored OAuth refresh tokens.
Audit-log payloads and exports written to object storage.

Some non-sensitive operational data is not encrypted with your key so the system can still function: opaque internal record IDs, timestamps, and tenant identifiers used for routing and row-level security. None of it reveals who a user is.

What never leaves sovereign storage

Independently of BYOK, identity records stay in the home region you pinned the project to. Encrypted or not, OrthID does not replicate user records, factors, or audit payloads out of that region. BYOK adds a second lock: even within the region, the data is only decryptable while your provider authorises it. The KEK itself never enters OrthID memory in usable form, never leaves your provider, and is never backed up by OrthID.

Note

BYOK and region pinning are complementary, not alternatives. Region pinning controls where the data lives; BYOK controls who can decrypt it. Read Regions & sovereignty for the full residency model.

Next steps

Regions & sovereignty to understand data residency and how it pairs with customer-managed keys.
Self-host to run OrthID in your own cloud alongside your own key provider.