Skip to main content
Back to blog

BYOK on a CPaaS, Without the Diagram Deck — Register, Activate, Rotate, Revoke

A buyer-to-procurement walkthrough of Devotel Orbit's customer-managed keys (BYOK) lifecycle — register the ARN from your own KMS, activate with enforce, rotate quarterly, revoke on off-boarding — mapped to the docs page's state machine and the exact four endpoint calls under /api/v1/compliance/byok.

Orbit Editorial Team

Quick answer: BYOK (bring your own key) lets your tenant register a reference to a key that lives in your own KMS — AWS KMS, Google Cloud KMS, Azure Key Vault, or HashiCorp Vault. Devotel Orbit stores the reference plus a truncated fingerprint, and no key material ever leaves your KMS. The lifecycle is a four-step state machine — register the key to pending, activate it to active (optionally with enforce: true), rotate it quarterly with a new reference, and revoke it on off-boarding — all through four calls under /api/v1/compliance/byok, and each step below maps to the matching section of the Customer-Managed Keys (BYOK) docs page.

If you are here because a procurement questionnaire asks about customer-managed encryption keys, skip to the buyer checklist section — it maps the question to the sentences in the docs you can quote as evidence, plus one honesty clause you should quote too.

Why BYOK comes with a procurement lens, not an architecture deck

The BYOK question rarely arrives from an engineer. It arrives in a vendor security review: "Does the platform support customer-managed encryption keys?" The answer a CPaaS gives determines how the review proceeds — a yes that is actually "we will hold your key material for you" reopens the risk conversation, and a no adds friction to the shortlist. What a buyer needs is the documented, drawable path: register, activate, rotate, revoke, with the exact calls and the exact guarantee about where the key material lives.

Orbit's BYOK is built as a control plane for your key reference, not a key vault. You hold the key in AWS KMS, Google Cloud KMS, Azure Key Vault, or HashiCorp Vault; Orbit records which reference governs your organization's key-management posture and echoes back a truncated fingerprint so a lower-privileged viewer never sees the full ARN or vault path. Writes are restricted to organization owners and admins — the same surface any security questionnaire asks about, stated in the docs as fact.

The lifecycle state machine, with the worked curl sequence

The docs page renders the state machine as a table; here is the same machine as an operator runs it. Three states — pending, active, revoked — and four verbs. Every register, activate, rotate, and revoke writes an audit-log entry, so the sequence below is also the evidence trail an auditor reads later.

1. Register — PUT /compliance/byok (arrives at pending)

Register the canonical reference for your provider — an AWS KMS key or alias ARN, a GCP CryptoKey resource name, an Azure key identifier URL, or a Vault transit path. The API validates the reference against the provider's canonical grammar and refuses a malformed one with 409 BYOK_INVALID_KEY_REFERENCE, so a typo fails here, not mid-activation.

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"
  }'

Pre-activate sanity check — GET /compliance/byok

Before you activate anything, read the record back. The GET is available to any authenticated user and never echoes the raw reference — you get the provider, the truncated fingerprint (kf_9f2a…), the state, the enforced flag, and the rotation count. This is also the call the troubleshooting page asks you to run first when something refuses, because state + enforced together decide which cause applies.

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

2. Activate — POST /compliance/byok/activate (pending → active)

Only a pending key can be activated; the endpoint returns 404 BYOK_NOT_FOUND with nothing registered and 409 BYOK_NOT_PENDING if the key is not pending. Pass enforce: true to record BYOK 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 }'

With enforce on, platform field-encryption calls that consult BYOK fail closed — they refuse with 409 BYOK_KEY_UNAVAILABLE if the key is revoked, unprovisioned, or its wrapped key cannot be recovered — rather than falling back silently to the platform key. When that 409 shows up, the BYOK_KEY_UNAVAILABLE troubleshooting page maps each cause (revoked, pending-only, unprovisioned wrapped key, unreachable KMS) to the check you run yourself, and names the escalation path (open a ticket with the request_id) for the rare ones you cannot resolve from your side.

3. Rotate — POST /compliance/byok/rotate (state unchanged, rotation_count + 1)

Rotation validates and re-fingerprints the new reference. An active key stays active; the rotation_count increments for provenance so the audit trail shows exactly which quarter's key governed. Rotation is refused on a revoked key — register anew instead — and on an enforced key it also re-wraps the internal data-encryption key, failing with 409 BYOK_REWRAP_FAILED rather than dropping enforcement silently.

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"
  }'

4. Revoke — POST /compliance/byok/revoke (→ revoked, terminal)

Revocation clears enforcement from your recorded policy and destroys the wrapped data-encryption key beyond recovery. Revoking twice returns 409 BYOK_ALREADY_REVOKED; to re-enable BYOK you register a key afresh with PUT.

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" }'

The same lifecycle runs in the dashboard at Settings → Compliance → Customer-Managed Keys, guarded to owner/admin roles — the API above is for the runbook you automate.

The read-this-twice clause: what enforce actually scopes to

Most BYOK pages sell the flag and leave the scoping to a footnote. Orbit's docs say it in the open, and a good review asks you to quote this part too: enforce records your organization's key-management policy for compliance evidence — a control-plane assertion. 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, and an active, enforced BYOK config gates the field-encryption seam rather than re-homing stored data under your key. That is the sentence that turns a procurement answer from a sales claim into an accurate one. The rest of this walkthrough is about operating the seam correctly.

The procurement dimension: where the question comes from

By the time a CPaaS buyer reaches the BYOK row, the pattern is well worn — it reads like this in the document a security or procurement team hands you: "Does the platform support customer-managed encryption keys (BYOK / CMEK)?" followed by three escalations: "If yes, which KMS providers?" and "Describe how key material is handled." and, in the stricter form, "Is it mandatory or optional?"

The BYOK docs page answers all four in quotable sentences:

  • Support: "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."
  • Providers: AWS KMS, Google Cloud KMS, Azure Key Vault, and HashiCorp Vault (Transit) — each with its canonical reference format validated at registration.
  • Key material handling: "No key material ever leaves your KMS. Orbit stores only the key reference and echoes back a truncated fingerprint."
  • Lifecycle: "You register a reference to the key… then activate, rotate, and revoke it through the full lifecycle."

Two properties make the answer hold up in review: the questionnaire's evidence requirement (audit-log entries on every register, activate, rotate, and revoke, readable in Settings → Audit Log) and the access boundary (writes restricted to organization owners and admins). Quote them together and the customer-managed-keys row stops being a blocker.

The quarterly rotation drill

Pair BYOK rotation with the four-check quarterly compliance review — it was written for exactly this kind of cadence — and key rotation becomes one line item instead of an event. A copy-paste runbook step for your quarter checklist:

BYOK rotation (10 minutes):

  1. Mint the new key version in your KMS for the registered provider.
  2. POST /api/v1/compliance/byok/rotate with the new key_reference.
  3. GET /api/v1/compliance/byok — confirm rotation_count incremented and state is still active.
  4. Close out your quarter binder knowing the BYOK posture row shows the fresh fingerprint (the evidence binder maps a quarter of posture in one download; proof exports and audit log carry the rotation entry).

If rotation on an enforced key fails with 409 BYOK_REWRAP_FAILED, that is the fail-closed seam refusing to drop enforcement — the troubleshooting page covers it; do not revoke-and-re-register to work around it.

Tenant-owned, opt-in, and where to look

BYOK is an opt-in posture control, the same way the rest of Orbit's compliance model works: platform-managed encryption protects tenant data either way, and you choose whether a customer-managed key should govern the field-encryption seam. No mandate in either direction — and, per the platform's tenant-owned framing, no surface in this walkthrough substitutes for your own risk assessment. If you leave it off, nothing in this post blocks you; if you turn it on, the four calls above are the whole contract.

Frequently asked questions

Does Orbit hold my key material?

No. You register a reference to a key that stays in your own KMS. Orbit stores the reference and a truncated fingerprint only, and no key material ever leaves your KMS — the docs guarantee this in the opening note, and the GET endpoint never echoes the raw reference.

Why is my activate call returning 409?

409 BYOK_NOT_PENDING means the key is not in the pending state — only a pending key can activate. If you enforced at a partial step, or hit a refused envelope call at encrypt time, the BYOK_KEY_UNAVAILABLE troubleshooting page maps the remaining causes (revoked, unprovisioned wrapped key, unreachable KMS) to their checks.

What does rotation change in the audit trail?

Each POST /rotate writes an audit-log entry and increments rotation_count, so the sequence of fingerprints plus counts is the provenance evidence of which key governed which period. An enforced key also re-wraps the internal data-encryption key under the new reference; a failed re-wrap refuses the rotation rather than dropping enforcement.

Can I revoke and re-register later?

Yes — revocation is terminal for that reference (409 BYOK_ALREADY_REVOKED on repeat), but re-registering a key afresh with PUT /compliance/byok re-enables BYOK cleanly.

Keep reading

BYOK on a CPaaS, Without the Diagram Deck — Register, Activate, Rotate, Revoke — Orbit by Devotel