Customer-Managed Keys (BYOK)

Bring Your Own Key (BYOK) is Orbit’s control plane for recording which encryption key — held in your external key-management system — governs your organization’s key-management posture. You register a reference to the key (an ARN, resource name, or vault path), then activate, rotate, and revoke it through the full lifecycle below.

No key material ever leaves your KMS. Orbit stores only the key reference and echoes back a truncated fingerprint — never the reference itself — so a lower-privileged viewer can’t see the exact ARN or vault path. Writes to this surface are restricted to organization owners and admins.

All endpoints below are rooted at https://api.orbit.devotel.io/api/v1/compliance/byok. The same lifecycle is available in the dashboard at Settings → Compliance → Customer-Managed Keys, guarded to owner/admin roles.

Lifecycle states

A registered key moves through this state machine:

From	Action	Endpoint	To
none / revoked	register	`PUT /compliance/byok`	`pending`
`pending`	activate (optional `enforce`)	`POST /compliance/byok/activate`	`active`
`pending` / `active`	rotate	`POST /compliance/byok/rotate`	same state, `rotation_count` + 1
`pending` / `active`	revoke	`POST /compliance/byok/revoke`	`revoked`

State	Meaning
`pending`	Registered and validated; not yet activated. Only a `pending` key can be activated.
`active`	You have granted Orbit’s service identity decrypt access and confirmed the key is live.
`revoked`	Key is withdrawn. Re-register afresh to re-enable BYOK.

Every register, activate, rotate, and revoke writes an audit-log entry — see Auditing.

What `enforce` does — and does not do

The enforce flag (set at activation, or toggled later) records your organization’s key-management policy for compliance evidence. It is a control-plane assertion, and it matters that you understand its exact scope:

It does not re-encrypt tenant data. Platform-managed field encryption (the encrypt-everything envelope Orbit applies to tenant data at rest) stays authoritative regardless of your BYOK config’s state.
You cannot point it back off casually once on: revocation clears it, and subsequent BYOK-gated operations behave as below.

When enforce is on, platform field-encryption calls that consult BYOK fail closed — they refuse to proceed with a 409 BYOK_KEY_UNAVAILABLE — if the key is revoked, unprovisioned (no wrapped data-encryption key yet), or its wrapped key cannot be recovered. They never fall back silently to the platform key when your policy says a customer key must govern. Do not interpret an active, enforced BYOK config as “tenant data is encrypted under my key” — today, tenant data at rest is protected by platform-managed encryption, and BYOK records your policy and gates the field-encryption seam.

Provider setup

Pick your KMS provider, copy its canonical key reference, and register it either in the dashboard (Settings → Compliance → Customer-Managed Keys) or via the API. The provider catalog (GET /compliance/byok) returns the exact expected format for each provider.

AWS KMS

arn:aws:kms:<region>:<account>:key/<uuid>

Example: arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

curl -X PUT https://api.orbit.devotel.io/api/v1/compliance/byok \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws_kms",
    "key_reference": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "key_alias": "Tenant data key",
    "justification": "SOC 2 evidence"
  }'

Google Cloud KMS

projects/<project>/locations/<location>/keyRings/<ring>/cryptoKeys/<key>

Example: projects/acme/locations/europe-west1/keyRings/orbit/cryptoKeys/tenant-data

curl -X PUT https://api.orbit.devotel.io/api/v1/compliance/byok \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gcp_kms",
    "key_reference": "projects/acme/locations/europe-west1/keyRings/orbit/cryptoKeys/tenant-data"
  }'

Azure Key Vault

https://<vault>.vault.azure.net/keys/<name>/<version>

Example: https://acme-kv.vault.azure.net/keys/orbit-tenant-data

curl -X PUT https://api.orbit.devotel.io/api/v1/compliance/byok \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "azure_keyvault",
    "key_reference": "https://acme-kv.vault.azure.net/keys/orbit-tenant-data"
  }'

HashiCorp Vault (Transit)

https://<vault-host>/v1/transit/keys/<name>

Example: https://vault.acme.internal/v1/transit/keys/orbit-tenant-data

curl -X PUT https://api.orbit.devotel.io/api/v1/compliance/byok \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "hashicorp_vault",
    "key_reference": "https://vault.acme.internal/v1/transit/keys/orbit-tenant-data"
  }'

The API validates the reference against the provider’s canonical grammar and rejects a malformed one with 409 BYOK_INVALID_KEY_REFERENCE.

Read the current config

GET /compliance/byok returns the registered config (or null when unset), the provider catalog, and the resolved posture. Available to any authenticated user; never echoes the raw reference.

curl https://api.orbit.devotel.io/api/v1/compliance/byok \
  -H "X-API-Key: $ORBIT_API_KEY"

{
  "data": {
    "config": {
      "provider": "aws_kms",
      "key_alias": "Tenant data key",
      "fingerprint": "kf_9f2a…",
      "state": "active",
      "enforced": true,
      "rotation_count": 1,
      "created_at": "2026-06-01T00:00:00.000Z",
      "activated_at": "2026-06-01T01:00:00.000Z",
      "rotated_at": "2026-08-01T00:00:00.000Z"
    },
    "providers": [ /* the provider catalog above */ ],
    "posture": {
      "enabled": true,
      "enforced": true,
      "state": "active",
      "provider": "aws_kms",
      "fingerprint": "kf_9f2a…"
    }
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

Activate

Mark a pending key active once you have granted Orbit’s service identity decrypt access. Pass enforce: true to record it as your organization’s governing key-management policy.

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/byok/activate \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enforce": true }'

If no key is registered the endpoint returns 404 BYOK_NOT_FOUND; if the key is not pending it returns 409 BYOK_NOT_PENDING.

Rotate

Replace the registered key reference with a new one. The new reference is validated and re-fingerprinted; an active key stays active and the rotation count bumps. Rotation is refused on a revoked key — register anew instead.

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/byok/rotate \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws_kms",
    "key_reference": "arn:aws:kms:us-east-1:111122223333:key/5678efgh-56ef-78gh-90ij-5678901234ab"
  }'

Rotation increments the rotation_count for provenance. For an enforced key it also re-wraps the internal data-encryption key under the new reference; if the existing wrapped key can’t be recovered the rotation is refused with 409 BYOK_REWRAP_FAILED rather than silently dropping enforcement.

Revoke

Withdraw the customer key. Revocation clears enforcement from your recorded policy and destroys the wrapped data-encryption key, so it can never be recovered again. It does not re-encrypt or otherwise affect stored tenant data — platform-managed encryption stays authoritative throughout.

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/byok/revoke \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "justification": "Key retired after annual rotation policy" }'

Revoking an already-revoked key returns 409 BYOK_ALREADY_REVOKED. To re-enable BYOK after revocation, register a key afresh with PUT.

Auditing

Every register, activate, rotate, and revoke writes an audit-log entry recording the provider, fingerprint, enforcement state, and (for revokes) your justification. Read it in the dashboard at Settings → Audit Log. For SOC 2 / ISO 27001 evidence, point auditors at the audit trail and cite the resolved BYOK posture in your Compliance Evidence Binder.

Posture Overview — the compliance toggle map, including where BYOK shows up.
Error Codes reference — the BYOK_KEY_UNAVAILABLE row and every BYOK-specific conflict code.
HIPAA posture — how PHI encryption is handled alongside your key-management policy.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Customer-Managed Keys (BYOK)

Customer-Managed Keys (BYOK)

Lifecycle states

What `enforce` does — and does not do

Provider setup

AWS KMS

Google Cloud KMS

Azure Key Vault

HashiCorp Vault (Transit)

Read the current config

Activate

Rotate

Revoke

Auditing

​Customer-Managed Keys (BYOK)

​Lifecycle states

​What enforce does — and does not do

​Provider setup

​AWS KMS

​Google Cloud KMS

​Azure Key Vault

​HashiCorp Vault (Transit)

​Read the current config

​Activate

​Rotate

​Revoke

​Auditing

​Related

Customer-Managed Keys (BYOK)

Lifecycle states

What `enforce` does — and does not do

Provider setup

AWS KMS

Google Cloud KMS

Azure Key Vault

HashiCorp Vault (Transit)

Read the current config

Activate

Rotate

Revoke

Auditing

Related