# BYOK setup (/guides/byok-setup)



Bring-your-own-key (BYOK) lets Zumik call the provider with **your** credential instead of the
platform's contracted account. You keep your existing provider agreement, rate limits, and billing
relationship; Zumik keeps the control plane - resolution, sessions, diagnostics, QoS, and purge
evidence - on top.

BYOK is first-class for all five primary providers: OpenAI, Anthropic, xAI, Google Gemini, and
Fireworks AI. Provider-native optimization stays active under your key - Anthropic `cache_control`
breakpoints, Gemini implicit caching, Fireworks dedicated-tier latency, and the OpenAI/Anthropic
Batch APIs all work as they do directly.

## How secrets are handled [#how-secrets-are-handled]

Your secret is sealed at rest with **AES-256-GCM** under a key derived from the platform's data key,
and used only to call your provider. The API never returns the secret again - only a one-way
fingerprint (`zfp_…`) so you can recognize which key is configured.

<Note>
  If a secret ever lands somewhere it shouldn't, treat it as compromised and rotate it at the
  provider, then [rotate](#rotate-a-key) the Zumik credential. Deleting alone does not un-leak a key.
</Note>

## Attach a key [#attach-a-key]

`POST /v2/provider-credentials`. `provider` is one of `openai`, `anthropic`, `xai`, `gemini`,
`fireworks_ai`.

```bash
curl https://api.zumik.ai/v2/provider-credentials \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "display_name": "Acme Anthropic - prod",
    "secret": "sk-ant-..."
  }'
```

```json title="Response"
{
  "id": "pcr_01jy…",
  "object": "provider_credential",
  "project_id": "prj_01jy…",
  "provider": "anthropic",
  "status": "active",
  "display_name": "Acme Anthropic - prod",
  "secret_fingerprint": "zfp_1a2b3c4d5e6f7a8b",
  "created_at": "2026-06-15T12:00:00Z",
  "metadata": {}
}
```

An empty `secret` returns `400` with param `secret`. The attach is written to the audit log
(`byok.credential.create`).

## How routing works [#how-routing-works]

On every request, the Execution Broker resolves your model to a provider. If the project has an active
BYOK credential for that provider, the request is served through **your** key on the
[BYOK profile](/infrastructure/bifrost#providers-and-execution-profiles) - not the platform's metered
managed path. BYOK never falls back to OpenRouter: your key is your explicit choice, so a provider
failure surfaces as an error rather than silently re-routing.

Which profile served a request comes back on `Agent-Execution-Profile: byok` (`/v1`) or as
`"execution_profile": "byok"` in the `/v2` response body.

## Billing implications [#billing-implications]

BYOK traffic bills against **your** provider account directly - Zumik does not meter the provider
spend. Zumik charges a control-plane fee per request (drawn from your prepaid credits), but the
per-token provider cost lands on your provider invoice, under your negotiated rates and
reservations. Use BYOK
when you have existing agreements, procurement constraints, customer-controlled billing, or
account-level retention policies you need to keep. See [Billing and budgets](/guides/billing-budgets).

## Rotate a key [#rotate-a-key]

`POST /v2/provider-credentials/{credential_id}/rotate` re-seals a new secret in place and updates the
fingerprint, with no change to the credential id - so routing is uninterrupted.

```bash
curl https://api.zumik.ai/v2/provider-credentials/pcr_01jy…/rotate \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"secret":"sk-ant-new..."}'
```

Rotate at the provider first, confirm the new key works, then rotate here - the old sealed secret is
overwritten on success.

## List and revoke [#list-and-revoke]

```bash
# List - secrets are never returned, only fingerprints
curl https://api.zumik.ai/v2/provider-credentials \
  -H "Authorization: Bearer zk_live_..."

# Revoke - matching traffic falls back to the metered managed path immediately
curl -X DELETE https://api.zumik.ai/v2/provider-credentials/pcr_01jy… \
  -H "Authorization: Bearer zk_live_..."
```

Revoking drops the sealed secret and returns `{ "id", "object": "provider_credential.deleted", "deleted": true }`.

## When to use BYOK [#when-to-use-byok]

BYOK is the right profile when the provider relationship needs to stay yours. Reach for it when you
have:

* An existing provider agreement, committed-spend discount, or quota reservation you want to keep using.
* Procurement constraints that require the provider to bill you directly.
* Customer-controlled billing - the spend lands on an account you own, not Zumik's metered path.
* Account-level retention or compliance policies you need provider-native caching to run under your key.

If none of those apply, the [managed-provider](/execution/managed-providers) default is simpler: Zumik's
contracted accounts give broad coverage and the same provider-native caching with no key to manage.
Already paying for a coding subscription? A [subscription credential](/guides/subscriptions) serves
eligible traffic from its bundled allowance at the cache-discounted price instead.

<Card title="Subscription credentials" icon="ticket" href="/guides/subscriptions">
  Already paying for Claude Code or ChatGPT Codex? Attach the subscription instead of a raw key and
  serve eligible traffic from its bundled allowance.
</Card>