Skip to content

BYOK: your own model provider keys

A project can store its own keys of a model provider (openai, anthropic, gemini, compat) so that calls are billed to the customer's provider account.

Endpoint Permission Answer
POST /v1/provider-credentials {provider, label, secret} project:manage 201 {id, provider, last4, fingerprint, …}
GET /v1/provider-credentials, GET …/{id} project:manage metadata only
DELETE /v1/provider-credentials/{id} project:manage 204, revoked
POST /v1/provider-credentials/{id}/test project:manage {ok, checked, detail}

Write-only

  • The secret is sealed with AES-256-GCM under the tenant's data key (T11 keyring, wrapped by the tenant KEK) with aad = "dx-byok/1" | organization | project | credential: a ciphertext copied to another project, organization or row does not open.
  • The table keeps the ciphertext, nonce, DEK version, last4 and fingerprint (HMAC-SHA-256 of the key under a subkey of the tenant DEK). No response, log or audit event carries the secret; a validation error never echoes it.
  • Revoking destroys the ciphertext; the row stays as a record.

Use

The gateway asks for the key per call (ByokGateway in extractit.admin.credentials): a credential revoked in the middle of a run stops the next call (fails closed), and every call made with it is recorded in the call ledger with credential_source="byok" (platform keys: "platform"), never with the key. A policy with byok_only allows only the providers that have an active credential.

POST …/test checks that the key opens; when the deployment configures a provider check (app.state.dx_byok_tester, a cassette in tests) it also asks the provider. Tests use fake keys only; no paid provider is called.