BYOK (Bring Your Own Key)

Overview

BYOK lets you supply your own API keys for OpenAI, Anthropic, or Google. When configured, Aira routes model calls through your account — giving you direct billing, higher rate limits, and full control over provider relationships.

BYOK is configured per API key. Each of your Aira API keys can have its own provider key configuration.

Set Provider Keys

POST /api/v1/api-keys/{id}/byok
Authorization: Bearer aira_live_xxxxx

Request Body

Field	Type	Required	Description
`providers`	object	Yes	Map of provider name to key config
`providers.{name}.api_key`	string	Yes	Your provider API key

Valid provider names: openai, anthropic, google.

Example Request

curl -X POST https://api.airaproof.com/api/v1/api-keys/key_01J8X.../byok \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "providers": {
      "openai": { "api_key": "sk-proj-abc123..." },
      "anthropic": { "api_key": "sk-ant-xyz789..." }
    }
  }'

Response (200 OK)

{
  "mode": "byok",
  "providers": ["openai", "anthropic"],
  "request_id": "req_01J8X..."
}

Response Fields

Field	Type	Description
`mode`	string	`byok` when custom keys are configured, `managed` otherwise
`providers`	string[]	List of providers with custom keys configured

Provider keys are encrypted at rest and never returned in API responses. You can overwrite them but not read them back.

Get BYOK Status

GET /api/v1/api-keys/{id}/byok
Authorization: Bearer aira_live_xxxxx

Returns the current BYOK configuration for an API key — which providers have custom keys set, without revealing the keys themselves.

Example Response

{
  "mode": "byok",
  "providers": ["openai", "anthropic"],
  "request_id": "req_..."
}

If no BYOK is configured:

{
  "mode": "managed",
  "providers": [],
  "request_id": "req_..."
}

Delete BYOK Configuration

DELETE /api/v1/api-keys/{id}/byok
Authorization: Bearer aira_live_xxxxx

Removes all custom provider keys and reverts to Aira-managed keys.

Delete a Single Provider

To remove only one provider while keeping the rest, pass the provider query parameter:

curl -X DELETE "https://api.airaproof.com/api/v1/api-keys/key_01J8X.../byok?provider=openai" \
  -H "Authorization: Bearer aira_live_xxxxx"

If other providers are still configured, the mode stays byok. If the deleted provider was the last one, mode reverts to cloud.

Response (200 OK)

{
  "mode": "byok",
  "message": "openai key removed",
  "request_id": "req_..."
}

Setting a provider key merges with existing configuration — it does not overwrite other providers. Setting OpenAI, then Anthropic, then Google results in all three being configured.

How It Works

You set provider keys on one of your Aira API keys
Each POST merges new providers with existing config — other providers are preserved
When that API key is used to execute a case, Aira uses your provider keys for model calls
Provider billing goes to your account, not Aira's
If a provider key is not set for a model's provider, Aira falls back to managed keys

This is transparent to the case API — request and response shapes are identical whether using BYOK or managed keys.

Self-Hosted Deployments

In self-hosted mode (DEPLOYMENT_MODE=selfhosted), BYOK is required for all providers — there are no Aira-managed keys. The dashboard reflects this by showing "Not configured" instead of "Managed by Aira" for unconfigured providers.

BYOK (Bring Your Own Key)

On this page