Bring Your Own Key

Why BYOK

• Keep enterprise discounts and committed-spend agreements with your provider.
• Use private endpoints (Azure OpenAI in your subscription, AWS Bedrock in your account, on-prem inference servers).
• Centralised gateway behaviour (fallback, audit, spend caps) without giving Meridian Blue a billing relationship with every upstream.

Supported providers

Any provider with an OpenAI-compatible REST surface, plus the providers Meridian Blue routes natively (Anthropic, Gemini). The provider name is a free-form lowercase string that has to match a model mapping — the resolver looks up your BYOK credential by (tenantId, provider, modelName).

Register a credential

curl https://api.meridianblue.ai/api/v1/provider-keys \
  -H "Authorization: Bearer $MERIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "name": "Acme prod OpenAI",
    "apiKey": "sk-proj-...",
    "allowedModels": ["gpt-4o", "gpt-4o-mini"]
  }'

Optional allowedModels restricts the credential to a subset of model names. Omit to allow every model from this provider.

How routing works

For every request, after picking a target mapping, the router looks up (your tenantId, mapping.provider, mapping.modelName) in the BYOK store. If a credential is registered, it overrides the platform key for that single request. Otherwise the platform key is used and you're billed at the platform rate.

The override is logged in the request's audit entry as "BYOK used for this request".

Rotation

Rotate via PATCH /api/v1/provider-keys/:id with a new apiKey. The old plaintext is overwritten in the encrypted blob — there's no recovery path. To revoke entirely, DELETE /api/v1/provider-keys/:id and routing falls back to the platform key on the next request.

Encryption

Provider keys are encrypted at rest with AES-256-GCM, with a per-tenant key derivation. The plaintext key never appears in logs and is decrypted only on the request hot path. Ciphertext format: iv:authTag:ciphertext (hex), stored verbatim.

One tenant cannot decrypt another tenant's BYOK ciphertext (verified by integration test) — the derivation salts in the tenantId.