TRACELANE_BYOK_MASTER_KEY. Entitled workspaces can instead
configure a customer KMS through the gateway’s security API. The dashboard’s
BYOK Keys page is a separate public-key fingerprint registry; registering
a fingerprint does not activate customer KMS encryption. Provider keys are
decrypted in memory when needed for dispatch.
Setting a customer KMS configuration and registering a dashboard fingerprint
require Business $799/mo or above. An organisation admin can rotate or
remove registered fingerprints.
Viewing KMS status or registered fingerprints has separate read access. Gateway
BYOK provider keys are available separately from those controls.
How envelope encryption works
Provider keys are sealed with AES-256-GCM (ring AEAD). Without a customer KMS configuration, the deployment master key protects the envelope. With a customer KMS configuration, the gateway uses a tenant data key wrapped by that KMS for provider-key envelopes. Each ciphertext is bound to its tenant and provider; a mismatched context fails authentication.TRACELANE_BYOK_MASTER_KEY
(32 bytes, base64-encoded). Customer KMS integration uses a wrapped tenant data
key for provider-key envelopes; it does not cover trace payloads.
Public-key fingerprint (audit)
You may register a Customer-Managed Key public-key fingerprint for audit and labeling. This registry does not configure the gateway’s customer KMS or change how provider keys are encrypted.Register a dashboard fingerprint
Dashboard (Settings → BYOK Keys)
- Generate a key pair:
- In the dashboard: Settings → BYOK Keys → Add Key.
- Paste the contents of
cmk-public.pem, choose a scope, click Register Key. - Store
cmk-private.pemin your secrets manager (AWS Secrets Manager, Vault, etc.) — never commit it to source control.
Fingerprint registry API
Scope
Prompt and completion text is not captured by default. The gateway records it
only when a workspace owner turns recording on (Prompt content),
and the first-party SDK provider adapters do not send message bodies. OpenTelemetry message fields are also kept only when the corresponding capture
half is enabled; sending them does not override the workspace decision. Recorded text is not encrypted under your key
today — the
trace-payload scope above is not available.
Customer KMS API
The gateway exposesGET, PUT, and DELETE /v1/security/kms, plus
POST /v1/security/kms/migrate and POST /v1/security/kms/rewrap.
Reading status requires settings-view access. Configuration changes require
the security-management capability; setting a new configuration also checks
the customer KMS entitlement. A PUT tests a wrap/unwrap round trip before
storing the configuration. Existing provider
keys sealed under the platform master key require an explicit migration:
after KMS is configured, those keys cannot be used until they are migrated.
Plan the configuration and migration together before sending provider traffic;
configuring KMS does not silently move the old ciphertext. The rewrap route
changes the KMS wrapping key for the tenant data key. Supported backends are
AWS KMS, Vault Transit, GCP KMS,
and Azure Key Vault. The dashboard fingerprint registry does not call these
endpoints.
Rotate & revoke dashboard fingerprints
Registering, listing, rotating, and removing CMK fingerprints is available via the dashboard (Settings → BYOK Keys) and its API. Rotation here is a registry operation: it records a replacement fingerprint and marks the previous onerotating. It does not rotate a gateway KMS configuration or re-encrypt
provider-key ciphertext.
Removing or replacing a provider key through the dashboard or API takes effect on
the next request the gateway instance serves: it evicts its cached copy of that
key. (Cached copies are otherwise refreshed on a timer.)
Audit trail
CMK register and remove operations are recorded against the tenant in the control plane. They are not currently written to the tamper-evident audit ledger, sotlane verify does not cover them.