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

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.

Attach a key

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

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

{
  "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

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 - 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

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.

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.

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 - 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

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 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 serves eligible traffic from its bundled allowance at the cache-discounted price instead.