Skip to main content
Use your own provider API keys with Auriko’s routing, monitoring, and fallback capabilities.

​
Prerequisites

  • An Auriko API key for inference
  • A session token for key management
  • Workspace owner or admin role (for key management)
  • A valid API key from a supported provider

​
Find your workspace ID

Your API key is scoped to a workspace. To discover your workspace ID, call /v1/me: 
curl https://api.auriko.ai/v1/me \
  -H "Authorization: Bearer $AURIKO_API_KEY"
The response includes your workspace_id: 
{
  "object": "api_key_identity",
  "workspace_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "tier": "explorer",
  "rate_limit_rpm": 60
}
You can also find your workspace ID in the dashboard under Settings.
workspace_id is null for keys created before workspace support.

​
Add a provider key

Provider key management uses session authentication. Get a session token from the dashboard, then register a provider key: 
curl -X POST https://api.auriko.ai/v1/workspaces/{workspace_id}/provider-keys \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "api_key": "sk-...",
    "label": "Production OpenAI",
    "validate_before_save": true
  }'
Response: 
{
  "id": "pk_abc123",
  "provider": "openai",
  "provider_name": "OpenAI",
  "key_prefix": "sk-...wxyz",
  "is_default": true,
  "validation_status": "valid",
  "detected_tier": "tier-5",
  "tier_source": "auto_detected",
  "created_at": "2026-03-20T10:00:00Z"
}
When validate_before_save is true (default), Auriko makes a lightweight probe request to the provider to verify the key works before saving it.

​
Supported providers

Provider identifierProvider name
openaiOpenAI
anthropicAnthropic Claude
google_ai_studioGoogle AI Studio
deepseekDeepSeek
xaixAI Grok
fireworks_aiFireworks AI
together_aiTogether AI
z_aiZ.AI
minimaxMiniMax
moonshotMoonshot AI

​
Tier detection

Auriko auto-detects your provider account tier from rate limit headers on first use. The detected tier affects available RPM and TPM limits for routing decisions. Override auto-detection:
  • Enterprise flag — set is_enterprise: true when adding a key to mark it as enterprise tier
  • Manual tier — for providers that require tier selection (for example, Google AI Studio), pass selected_tier at key creation
  • Update later — PATCH /v1/workspaces/{workspace_id}/provider-keys/{id}/tier to change the tier after creation
Once a tier is manually set (tier_source: "user_specified"), auto-detection is disabled for that key.

​
Use BYOK in requests

Control key source with routing constraints: 
import os
from auriko import Client

client = Client(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1"
)

# Use only your own keys
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    routing={"only_byok": True}
)

# Use only platform keys (no BYOK)
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    routing={"only_platform": True}
)

​
Routing behavior

The router prefers your BYOK key when one exists for the requested provider. You get direct billing control and your provider tier applies. The router falls back to platform keys in two cases:
  1. Exhausted: your BYOK key has zero remaining rate-limit headroom and the platform key has capacity.
  2. Fetch failure: your BYOK key can’t be retrieved or decrypted at request time and a platform key is available.
Override the default with routing constraints:
  • only_byok: true: use only your BYOK key and fail the request if unavailable.
  • only_platform: true: ignore BYOK keys entirely.

​
Manage keys

These endpoints also use session authentication: 
# List all provider keys
curl https://api.auriko.ai/v1/workspaces/{workspace_id}/provider-keys \
  -H "Authorization: Bearer $SESSION_JWT"

# Delete a key
curl -X DELETE https://api.auriko.ai/v1/workspaces/{workspace_id}/provider-keys/{id} \
  -H "Authorization: Bearer $SESSION_JWT"

# Re-validate a key
curl -X POST https://api.auriko.ai/v1/workspaces/{workspace_id}/provider-keys/{id}/validate \
  -H "Authorization: Bearer $SESSION_JWT"

# Set as default for provider
curl -X POST https://api.auriko.ai/v1/workspaces/{workspace_id}/provider-keys/{id}/set-default \
  -H "Authorization: Bearer $SESSION_JWT"

​
Security

Auriko encrypts your provider keys and isolates them per workspace.
  • Encrypted at rest: XSalsa20-Poly1305 with per-workspace HKDF-SHA256 key derivation.
  • Masked in responses: API responses return keys as sk-xxxxx...**** with only the first 8 characters visible.
  • Decrypted at request time only: the edge router decrypts your key when calling the provider, then discards it.
  • Never logged: Auriko never logs or persists decrypted keys.
  • Key rotation supported: encryption key versions are tracked per key for zero-downtime master key rotation.

​
Data policies

BYOK keys inherit the account-level data policy. Options: none, no_training, and zdr (zero data retention). When a per-request data policy intersects with the account-level policy, the most restrictive one wins. For more on data policies, see Advanced routing — Data policy.

​
Rate limiting

Auriko rate-limits BYOK management endpoints to 20 operations per minute per user. Permissions: owner and admin for add, delete, and tier changes; all members can list keys and use them in requests.