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,
last4andfingerprint(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.