Encryption and BYOK
The Encryption page on every plan, and how an Enterprise owner connects a customer-managed key (BYOK) to wrap the workspace data keys.
Path: Encryption (/settings/encryption), a top-level sidebar row because the wrapping key is a property of your whole workspace. Envelope model, AAD binding, the same floor on every plan, and the no-fallback rule: encryption in the cloud.
Page layout
Without your own key, the page shows three facts, the three layers that seal a value, and Bring your own key. The facts:
- The
AES-256-GCMcipher - The binding to each value's full address
- The wrapping key, held by us
| Plan | Bring your own key |
|---|---|
| Enterprise | Opens the connect form |
| Pro | Links to the add-on |
| Free | Links to a contact page |
Only an owner can connect a key.
The binding fact shows the address of the newest parameter you can read, as project / environment / NAME. When you can read none, it shows that pattern itself. It never shows a name from a project you cannot open, and never a value.
With a customer-managed key: the same three facts, the wrapping key held by you, then three tabs.
| Tab | Content |
|---|---|
| Key | Status, provider, tail of the key reference, region, AES-256-GCM, last verified. Stand down and abandon sit under Advanced |
| Rotation | Every re-wrap, newest first, with direction and N of M re-wrapped. Shown once a re-wrap exists |
| Access | Who can change the key, the step-up factor, who connected it and when |
Key backends (Enterprise)
| Backend | We need |
|---|---|
| AWS KMS | Key reference and a key policy allowing us to wrap and unwrap |
| Google Cloud KMS | Key reference and a workload identity federation grant |
| Azure Key Vault | Key reference and an admin consent round trip |
| HashiCorp Vault Transit | Key reference and a federation grant |
The page shows the issuer, subject and audience your key service must trust.
Connecting starts a re-wrap: we unwrap every stored data key under the current key and re-wrap it under yours. We leave sealed value bytes untouched and open no value.
Key states
| State | Meaning |
|---|---|
pending | Connected, waiting on its first check |
rewrapping | Re-wrap running |
active | Your key is the wrapping key |
disabling | Stand-down running |
revoked | Your key refused us; nothing opens under it |
failed | The connect did not complete |
retired | Superseded by a later key |
You can resume, re-check, or abandon a half-finished connect. The Azure consent round trip reports consented, declined, expired, unverified, not_authorized or not_configured on the page. The account that signs in must be a directory admin (Global, Privileged Role, Cloud Application or Application Administrator) or be able to read the key in Key Vault; not_authorized means it was neither.
We do not gate standing your key down on plan, so after a lapsed plan you can always take your key back.
Required permissions
No action carries a permission slug (roles and permissions): owner is the gate, and connect, resume and finish also check that Enterprise or the add-on includes customer-managed keys.
| Action | Needs | Step-up | Recorded as |
|---|---|---|---|
| Read the page | org:read | No | nothing |
| Connect a customer-managed key | Owner, Enterprise | Yes | org.byok_rewrap_started |
| Resume a half-finished connect | Owner, Enterprise | No | org.byok_rewrap_started |
| Finish the Azure consent round trip | Owner, Enterprise | No | org.byok_rewrap_started |
| Re-check a key | Owner | Yes | org.byok_rechecked |
| Cancel a pending grant | Owner | Yes | org.byok_connect_canceled |
| Abandon a pending key | Owner | Yes | org.byok_abandoned |
| Stand the key down | Owner | Yes | org.byok_disable_requested |
Our re-wrap job writes its own entries: org.byok_activated (your key takes over), org.byok_disabled (stood down), org.byok_revoked (your key refused), org.byok_rewrap_failed (did not complete). Each is in the audit action picker: browsing the record.
Next: plans and seats.