> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# BYOK: register, activate, rotate, and revoke customer-managed keys

> Walk Settings → Compliance → Customer-Managed Keys: register a key reference from your own KMS (AWS KMS, Google Cloud KMS, Azure Key Vault, HashiCorp Vault), activate it with enforcement, rotate the reference with zero downtime, and revoke it for off-boarding — with the audit trail each step writes.

# BYOK: register, activate, rotate, and revoke customer-managed keys

Bring Your Own Key (BYOK) is Orbit's key-management control plane for compliance evidence: it records which encryption key — held in **your** external KMS — governs your organization's key-management posture, and lets you prove and revoke that posture at will. This guide walks the full lifecycle from the dashboard, step by step.

The **Customer-Managed Keys** page lives at **Settings → Compliance → Customer-Managed Keys** and is guarded to **owner** and **admin** roles. The full endpoint surface, provider-by-provider reference formats, and error-code tables are in the [BYOK reference](/compliance/byok-customer-managed-keys); this page is the walkthrough.

<Note>
  Every step here is a tenant-owned control: you pick the key, you grant and
  revoke access in your own KMS, and you register the posture for evidence.
  No step is gated or mandated by the platform — and no step weakens the
  platform-managed encryption that always protects tenant data at rest.
</Note>

***

## 1. The BYOK model: your KMS, no key material in Orbit

BYOK supports four providers, each validated against its canonical reference format:

| Provider         | You register              | Example                                                                      |
| ---------------- | ------------------------- | ---------------------------------------------------------------------------- |
| AWS KMS          | A key or alias ARN        | `arn:aws:kms:us-east-1:111122223333:key/1234abcd-…`                          |
| Google Cloud KMS | A CryptoKey resource name | `projects/acme/locations/europe-west1/keyRings/orbit/cryptoKeys/tenant-data` |
| Azure Key Vault  | A key identifier URL      | `https://acme-kv.vault.azure.net/keys/orbit-tenant-data`                     |
| HashiCorp Vault  | A transit key path        | `https://vault.acme.internal/v1/transit/keys/orbit-tenant-data`              |

Three properties define the model:

* **No key material ever leaves your KMS.** Orbit stores only the key *reference* and its fingerprint. Read views echo back a truncated fingerprint — never the raw ARN or vault path — so a lower-privileged viewer can't see the exact location of your key.
* **This surface makes no KMS network call.** Registration is a control-plane recording: Orbit validates the reference's shape and fingerprints it, but the custody of the key itself stays with you, inside your own KMS boundary.
* **Platform-managed encryption stays authoritative.** Tenant data at rest is protected by Orbit's encrypt-everything envelope regardless of your BYOK config's state. Registration and enforcement record your compliance posture; they do not re-encrypt tenant data under your key. Do not read an active, enforced config as "tenant data is encrypted under my key."

A key moves through one state machine, and every transition writes an audit-log entry:

| From                 | Action                          | To                             |
| -------------------- | ------------------------------- | ------------------------------ |
| none / revoked       | Register                        | `pending`                      |
| `pending`            | Activate (optional enforcement) | `active`                       |
| `pending` / `active` | Rotate                          | same state, rotation count + 1 |
| `pending` / `active` | Revoke                          | `revoked`                      |

## 2. Register a key

Open **Settings → Compliance → Customer-Managed Keys → Register a customer-managed key**. You need the **owner** or **admin** role.

1. **KMS provider** — pick the provider that holds the key. The reference-format hint below the input updates to match.
2. **Key reference** — paste the canonical identifier (ARN, resource name, vault URL, or transit path). The server validates it against the provider's grammar; a malformed reference is refused with `409 BYOK_INVALID_KEY_REFERENCE`.
3. **Key alias** (optional) — a human-readable label shown wherever the fingerprint would be cryptic.
4. **Justification** (optional) — free text recorded with the registration; use it to cite the policy or clause that requires customer-managed keys (e.g. a security addendum).

Select **Register key**. The key lands in `pending` state with one audit-log entry.

<Warning>
  Registering replaces the recorded posture for the whole organization.
  Register is only available when no key exists or the previous key was
  revoked — while a key is `pending` or `active`, the register card is
  hidden and the action is refused.
</Warning>

## 3. Activate, and what enforcement records

From `pending`, the page asks two things of you before activation:

1. **Grant Orbit's service identity decrypt access on the key in your KMS** (a key policy statement in AWS, a CryptoKey IAM binding in Google Cloud, an access policy in Azure, a Vault policy in HashiCorp). The key stays pending until your side of the access grant exists.
2. **Activate** — with the optional **Enforce immediately** checkbox.

The enforcement checkbox records this key as your organization's **governing key-management policy for compliance evidence**:

* It does **not** re-encrypt tenant data — the platform envelope stays authoritative, as above.
* While enforcement is on, platform field-encryption calls that consult BYOK fail **closed** with `409 BYOK_KEY_UNAVAILABLE` when the key is revoked, unprovisioned, or its wrapped key is unrecoverable. They never fall back silently to the platform key when your recorded policy says a customer key must govern.
* Enforcement is cleared by revocation — that is the deliberate exit ramp, and it's irreversible (see Section 4).

Activate without enforcement to keep the registration advisory; you can rotate or revoke either way. Every activation writes an audit entry with the fingerprint and the enforcement flag.

## 4. Rotate with zero downtime — and revoke deliberately

### Rotate

From `pending` or `active`, select **Rotate key** and submit a new reference in the same form as registration. Rotation is a control-plane re-wrap, not a data migration:

* An `active` key stays `active` and its enforcement is preserved — no re-registration, no downtime window.
* The rotation count increments for provenance, so your audit trail shows each replacement as a first-class event.
* For an enforced key, the internal data-encryption key is unwrapped under the old reference and re-wrapped under the new one in the same operation. If the old wrapped key cannot be recovered, the rotation is **refused** with `409 BYOK_REWRAP_FAILED` rather than silently dropping enforcement — fix the reference and retry, or revoke and re-register as below.

### Revoke

Revoke is the deliberate off-boarding step — contract termination, a security addendum lapsing, or a key retirement policy:

1. Select **Revoke key**, optionally record a justification (e.g. the termination clause), and confirm in the destructive-action dialog.
2. Revocation clears the key from your recorded enforcement policy and destroys the wrapped data-encryption key, so it can never be unwrapped again. This confirmation step is intentional — re-enabling BYOK after revocation means registering a fresh key.
3. Revoking does **not** re-encrypt or crypto-shred tenant data. Platform-managed encryption is the system of record for tenant data throughout, so no stored field becomes unreadable.

Revoking an already-revoked key returns `409 BYOK_ALREADY_REVOKED`. To re-enable BYOK after a revoke, register a fresh key from Section 2.

## 5. Operations: health, failure modes, and the audit tie

**Monitor key health.** The config card shows the provider, alias, fingerprint, enforcement flag, rotation count, and the registered / activated / last-rotated timestamps, refreshed every 60 seconds — a sister tab's change lands on yours without a manual reload. `GET /compliance/byok` returns the same picture for automation: the config, the provider catalog, and the resolved posture.

**Failure modes when the KMS is unreachable.** This surface never calls out to your KMS, so a KMS outage cannot block registration or the dashboard. The failure modes live at the boundaries:

* If Orbit's service identity **loses decrypt access** on the key (a revoked grant, a deleted key version, a suspended KMS account), `pending` registration and rotation still work — but an enforced key's fail-closed seam refuses with `409 BYOK_KEY_UNAVAILABLE`, and an active key's re-wrap on rotation refuses with `409 BYOK_REWRAP_FAILED`. Restore the grant in your KMS, then retry the operation that failed.
* A malformed or abandoned reference (deleted key in a recycled ARN region, a retired vault path) fails loudly at register or rotate time with `409 BYOK_INVALID_KEY_REFERENCE` on the shape, or at re-wrap time against the old fingerprint.
* Enforcement refusing with a retryable failure means the recorded policy still stands; revocation is the only exit that clears it, and that too writes an audit entry.

**Audit trail.** Every register, activate, rotate, and revoke writes an audit-log entry with the provider, the fingerprint, the enforcement flag, and (for revokes) your justification. Filter **Settings → Audit log** by the key's fingerprint to reconstruct the full lifecycle — see the [audit log guide](/guides/audit-log) for filtering and export. For SOC 2 or ISO 27001 evidence, point auditors at that trail and cite the resolved BYOK posture in your [evidence binder](/compliance/evidence-binder).

## See also

* [Customer-Managed Keys (BYOK) reference](/compliance/byok-customer-managed-keys) — endpoint surface, provider grammar, and every `409 BYOK_*` conflict code
* [Compliance evidence binder](/compliance/evidence-binder) — cite your resolved BYOK posture as evidence
* [Security console: IP allowlist, SAML, SCIM, and 2FA](/guides/settings-security-console) — the org-level access controls next to this key plane
* [Audit log](/guides/audit-log) — filter the fingerprint's full lifecycle
* [HIPAA posture](/compliance/hipaa) — how PHI encryption reads alongside your key-management policy