OrthıD
Browse the docs
Guides

BYOK (bring your own keys)

Hold the keys to your own identity data. On your managed sovereign cell, bring-your-own-keys encrypts sensitive records with a key you own in Vault, AWS KMS, or an HSM, so the data is unreadable without your authorisation. BYOK and HSM custody are on the roadmap and available to design partners.

Preview
Customer-managed keys (BYOK) and HSM custody are in development and available to design partners. This guide describes the planned key model; the configuration and commands below are illustrative of that target.

OrthID encrypts sensitive fields at the application layer before they ever reach Postgres. By default it manages the encryption key for you. In the planned BYOK model, 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 your region-pinned cell 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.

Connect your key provider

You choose a provider - HashiCorp Vault, AWS KMS, or a PKCS#11 HSM - and grant your cell access to a single key. 3verest connects your cell to it as part of provisioning your sovereign cell. Your provider must allow the OrthID cell 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, and the KEK material never leaves your provider.

Key rotation

You rotate the KEK in your provider on whatever schedule your policy requires - for example a Vault Transit key rotation or a new KMS key version. Your cell adopts the new version 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 re-wrap that 3verest can run on demand.

Keep old key versions until re-wrap 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 the background re-wrap 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