Skip to content

Provider Keys API ​

All endpoints are prefixed with /api/settings/provider-keys.

Authentication is required via JWT cookie or Authorization: Bearer <token> header.

Model Sources and Direct Routes ​

Setting an API key for a provider enables that provider as a direct model source in the Model Browser. Models from that provider appear as available options and can be selected for chat requests.

Configured keys unlock direct routing for chat requests. The chat router calls resolve_key to find the best available key for the requested provider — if a direct key exists (at any tier), the request is sent to the provider's API instead of through OpenRouter. Direct routes offer lower latency and no markup on top of the provider's published pricing. If no key is configured for a provider, the system routes through OpenRouter when that model is available there.

Cloud Endpoints ​

Cloud-tier endpoints require the cloud_admin or platform_admin role.

List Cloud Provider Keys ​

GET /api/settings/provider-keys/cloud

Returns the status of all supported providers at the cloud tier.

Response 200 OK

json
[
  {
    "provider": "openai",
    "has_key": true,
    "key_display": "sk-proj...7x4q",
    "state": "active",
    "locked": false,
    "locked_above": false,
    "disabled_above": false,
    "source_tier": "cloud",
    "validated_at": "2026-02-09T12:00:00",
    "validation_error": null,
    "health_status": "healthy",
    "last_health_check": "2026-02-09T14:30:00",
    "health_message": "Key valid",
    "consecutive_failures": 0,
    "quota_remaining": null,
    "quota_limit": null,
    "expires_at": null,
    "rotation_reminder_days": 90,
    "last_rotated_at": "2026-01-15T10:00:00",
    "label": "Production key"
  },
  {
    "provider": "openrouter",
    "has_key": false,
    "key_display": null,
    "state": "active",
    "locked": false,
    "locked_above": false,
    "disabled_above": false,
    "source_tier": null,
    "validated_at": null,
    "validation_error": null,
    "health_status": "unknown",
    "last_health_check": null,
    "health_message": null,
    "consecutive_failures": 0,
    "quota_remaining": null,
    "quota_limit": null
  }
]

curl example:

bash
curl -s -b cookies.txt \
  https://your-instance.com/api/settings/provider-keys/cloud

Set Cloud Provider Key ​

PUT /api/settings/provider-keys/cloud/{provider}

Set or update a provider key at the cloud tier.

Path Parameters:

ParameterTypeDescription
providerstringProvider identifier (see Supported Providers below)

Request Body:

json
{
  "key": "sk-proj-abc123...",
  "locked": false
}
FieldTypeRequiredDescription
keystringYesThe provider API key
lockedbooleanNoLock to prevent lower-tier overrides (default: false)

Response 200 OK

json
{
  "provider": "openai",
  "has_key": true,
  "key_display": "sk-proj...3abc",
  "state": "active",
  "locked": false,
  "locked_above": false,
  "disabled_above": false,
  "source_tier": "cloud",
  "validated_at": null,
  "validation_error": null,
  "health_status": "unknown",
  "last_health_check": null,
  "health_message": null,
  "consecutive_failures": 0,
  "quota_remaining": null,
  "quota_limit": null
}

curl example:

bash
curl -s -b cookies.txt -X PUT \
  -H "Content-Type: application/json" \
  -d '{"key": "sk-proj-abc123...", "locked": false}' \
  https://your-instance.com/api/settings/provider-keys/cloud/openai

Delete Cloud Provider Key ​

DELETE /api/settings/provider-keys/cloud/{provider}

Remove a provider key at the cloud tier.

Response 200 OK

json
{
  "success": true,
  "message": "Cloud openai key removed"
}

curl example:

bash
curl -s -b cookies.txt -X DELETE \
  https://your-instance.com/api/settings/provider-keys/cloud/openai

Test Cloud Provider Key ​

POST /api/settings/provider-keys/cloud/{provider}/test

Validate a key without saving it. Makes a lightweight API call to the provider.

Request Body:

json
{
  "key": "sk-proj-abc123..."
}

Response 200 OK

json
{
  "valid": true,
  "error": null,
  "provider": "openai"
}

Error response example:

json
{
  "valid": false,
  "error": "Incorrect API key provided: sk-proj...****. You can find your API key at https://platform.openai.com/account/api-keys.",
  "provider": "openai"
}

Organization Endpoints ​

Organization-tier endpoints require the admin or owner role in the user's organization. Feature flag: org_shared_keys (Team tier and above).

List Organization Provider Keys ​

GET /api/settings/provider-keys/organization

Returns the status of all providers for the user's organization, including lock/disable state inherited from the cloud tier.

Response 200 OK — Same schema as cloud list, with locked_above and disabled_above reflecting cloud-tier state.

curl example:

bash
curl -s -b cookies.txt \
  https://your-instance.com/api/settings/provider-keys/organization

Set Organization Provider Key ​

PUT /api/settings/provider-keys/organization/{provider}

Set or update a provider key for the organization. Blocked if the cloud tier has locked or disabled this provider.

Request Body:

json
{
  "key": "sk-or-v1-abc123...",
  "locked": true
}

Error Responses:

StatusCondition
403Cloud tier has locked this provider
403Cloud tier has disabled this provider
403User is not an organization admin
400Unsupported provider

curl example:

bash
curl -s -b cookies.txt -X PUT \
  -H "Content-Type: application/json" \
  -d '{"key": "sk-or-v1-abc123...", "locked": true}' \
  https://your-instance.com/api/settings/provider-keys/organization/openrouter

Delete Organization Provider Key ​

DELETE /api/settings/provider-keys/organization/{provider}

Response 200 OK

json
{
  "success": true,
  "message": "Organization openrouter key removed"
}

Test Organization Provider Key ​

POST /api/settings/provider-keys/organization/{provider}/test

Same schema as cloud test endpoint.


User Endpoints ​

User-tier endpoints are available to any authenticated user with the byok feature flag (all subscription tiers).

List User Provider Keys ​

GET /api/settings/provider-keys/user

Returns provider status for the current user, including lock/disable state from cloud and tenant tiers.

Response 200 OK — Same schema as cloud list, with locked_above and disabled_above reflecting both cloud and tenant tier state.

curl example:

bash
curl -s -b cookies.txt \
  https://your-instance.com/api/settings/provider-keys/user

Set User Provider Key ​

PUT /api/settings/provider-keys/user/{provider}

Set or update a personal provider key. Blocked if cloud or tenant tier has locked/disabled this provider. Users cannot set the locked flag.

Request Body:

json
{
  "key": "tvly-abc123...",
  "locked": false
}

Error Responses:

StatusCondition
403Cloud tier has locked this provider
403Cloud tier has disabled this provider
403Organization tier has locked this provider
403Organization tier has disabled this provider
400Unsupported provider

curl example:

bash
curl -s -b cookies.txt -X PUT \
  -H "Content-Type: application/json" \
  -d '{"key": "tvly-abc123...", "locked": false}' \
  https://your-instance.com/api/settings/provider-keys/user/tavily

Delete User Provider Key ​

DELETE /api/settings/provider-keys/user/{provider}

Response 200 OK

json
{
  "success": true,
  "message": "User tavily key removed"
}

Test User Provider Key ​

POST /api/settings/provider-keys/user/{provider}/test

Same schema as cloud test endpoint.


Resolution Endpoint ​

Get Resolved Provider Keys ​

GET /api/settings/provider-keys/resolved

Returns the effective resolved key for each provider for the current user context, after applying the full resolution algorithm (User → Tenant → Cloud). Environment keys are automatically registered as platform defaults on startup, so a separate .env fallback is only reached if registration was skipped or the cloud key was deleted mid-session.

No actual key values are returned — only metadata.

Response 200 OK

json
[
  {
    "provider": "openai",
    "is_available": true,
    "source_tier": "user",
    "key_display": "sk-proj...7x4q",
    "is_locked": false,
    "is_disabled_at": null,
    "health_status": "healthy",
    "health_message": "Key valid",
    "quota_remaining": null,
    "quota_limit": null
  },
  {
    "provider": "openrouter",
    "is_available": true,
    "source_tier": "cloud",
    "key_display": "sk-or-v...x9ab",
    "is_locked": true,
    "is_disabled_at": null,
    "health_status": "healthy",
    "health_message": "Key valid",
    "quota_remaining": 8500,
    "quota_limit": 10000
  },
  {
    "provider": "tavily",
    "is_available": false,
    "source_tier": null,
    "key_display": null,
    "is_locked": false,
    "is_disabled_at": "tenant",
    "health_status": "unknown",
    "health_message": null,
    "quota_remaining": null,
    "quota_limit": null
  }
]

curl example:

bash
curl -s -b cookies.txt \
  https://your-instance.com/api/settings/provider-keys/resolved

Health Endpoints ​

Health endpoints require the key_health_monitoring feature flag (Team tier and above).

Get All Provider Health ​

GET /api/settings/provider-keys/health

Returns health summary for all providers at the cloud tier.

Response 200 OK

json
[
  {
    "provider": "openai",
    "health_status": "healthy",
    "last_health_check": "2026-02-09T14:30:00",
    "health_message": "Key valid",
    "consecutive_failures": 0,
    "quota_remaining": null,
    "quota_limit": null
  },
  {
    "provider": "gemini",
    "health_status": "degraded",
    "last_health_check": "2026-02-09T14:30:00",
    "health_message": "High latency: 2350ms",
    "consecutive_failures": 0,
    "quota_remaining": null,
    "quota_limit": null
  }
]

Get Provider Health Detail ​

GET /api/settings/provider-keys/health/{provider}

Returns health detail for a single provider.


Trigger Health Check ​

POST /api/settings/provider-keys/{tier}/{provider}/check

Trigger an immediate health check for a provider key at a specific tier.

Path Parameters:

ParameterTypeValues
tierstringcloud, tenant, user
providerstringProvider identifier

Permissions:

TierRequired Role
cloudCloud admin
tenantOrganization admin
userAuthenticated user (own keys only)

Response 200 OK

json
{
  "provider": "openai",
  "health_status": "healthy",
  "last_health_check": null,
  "health_message": "Key valid",
  "consecutive_failures": 0,
  "quota_remaining": null,
  "quota_limit": null
}

curl example:

bash
curl -s -b cookies.txt -X POST \
  https://your-instance.com/api/settings/provider-keys/cloud/openai/check

Get Health History ​

GET /api/settings/provider-keys/health/{provider}/history

Returns the health check history for a provider (cloud tier). Requires the key_health_history feature flag (Business tier and above).

Response 200 OK

json
[
  {
    "id": "abc123-...",
    "status": "healthy",
    "message": "Key valid",
    "latency_ms": 245,
    "quota_remaining": null,
    "checked_at": "2026-02-09T14:30:00"
  },
  {
    "id": "def456-...",
    "status": "unhealthy",
    "message": "Authentication failed - key may be revoked",
    "latency_ms": 120,
    "quota_remaining": null,
    "checked_at": "2026-02-09T14:15:00"
  }
]

curl example:

bash
curl -s -b cookies.txt \
  https://your-instance.com/api/settings/provider-keys/health/openai/history

Audit Endpoint ​

Get Organization Key Audit ​

GET /api/settings/provider-keys/organization/audit

Returns the audit trail of provider key changes for the user's organization. Requires the key_audit feature flag (Business tier and above) and organization admin role.

Response 200 OK

json
[
  {
    "id": "audit-123-...",
    "tier": "tenant",
    "provider": "openai",
    "action": "set",
    "actor_id": "user-456-...",
    "details": "{\"key_prefix\": \"sk-proj\", \"locked\": false}",
    "created_at": "2026-02-09T10:00:00"
  },
  {
    "id": "audit-124-...",
    "tier": "tenant",
    "provider": "openai",
    "action": "lock",
    "actor_id": "user-456-...",
    "details": null,
    "created_at": "2026-02-09T10:05:00"
  },
  {
    "id": "audit-125-...",
    "tier": "tenant",
    "provider": "tavily",
    "action": "delete",
    "actor_id": "user-789-...",
    "details": null,
    "created_at": "2026-02-08T16:30:00"
  }
]

curl example:

bash
curl -s -b cookies.txt \
  https://your-instance.com/api/settings/provider-keys/organization/audit

Error Responses ​

All endpoints return standard error responses:

StatusMeaning
400Bad request (unsupported provider, invalid input)
401Not authenticated
403Insufficient permissions (wrong role, locked/disabled provider)
404Resource not found (no key at specified tier, no organization)
500Internal server error

Error format:

json
{
  "detail": "Provider 'openai' is locked at the cloud tier"
}

Key Rotation & Expiry Endpoints ​

Set Key Expiry ​

PUT /api/settings/provider-keys/{tier}/{provider}/expiry

Set or update the expiry date, rotation reminder, and label for a provider key.

Path Parameters:

ParameterTypeValues
tierstringcloud, organization, user
providerstringProvider identifier

Request Body:

json
{
  "expires_at": "2026-06-01T00:00:00Z",
  "rotation_reminder_days": 90,
  "label": "Production key Q2 2026"
}
FieldTypeRequiredDescription
expires_atstring (ISO 8601)NoWhen the key expires (null to clear)
rotation_reminder_daysintegerNoDays before expiry to warn (default: 90)
labelstringNoFriendly label for the key

Response 200 OK -- Returns the updated ProviderKeyStatus object.


List Expiring Keys ​

GET /api/settings/provider-keys/expiring?within_days=30

Returns all keys expiring within the specified number of days.

Query Parameters:

ParameterTypeDefaultDescription
within_daysinteger30Number of days to look ahead

Response 200 OK

json
[
  {
    "id": "key-123-...",
    "tier": "tenant",
    "tier_id": "org-456",
    "provider": "openai",
    "expires_at": "2026-03-01T00:00:00Z",
    "rotation_reminder_days": 90,
    "label": "Production key"
  }
]

Usage Tracking Endpoints ​

Usage data is recorded in real time via record_usage on every LLM and search request, so these endpoints return live data reflecting actual platform activity.

Get Usage Summary ​

GET /api/settings/provider-keys/{tier}/usage/summary?days=30&provider=openai

Returns aggregate usage metrics for a tier.

Path Parameters:

ParameterTypeValues
tierstringcloud, organization, user

Query Parameters:

ParameterTypeDefaultDescription
daysinteger30Lookback period in days
providerstring(all)Filter to a specific provider

Response 200 OK

json
{
  "total_requests": 1250,
  "total_tokens": 485000,
  "total_cost_usd": 12.45,
  "success_count": 1230,
  "error_count": 20,
  "avg_latency_ms": 342.5,
  "period_days": 30
}

Get Usage by Provider ​

GET /api/settings/provider-keys/{tier}/usage/by-provider?days=30

Returns usage metrics grouped by provider.

Response 200 OK

json
[
  {
    "provider": "openai",
    "total_requests": 800,
    "total_tokens": 320000,
    "total_cost_usd": 8.50,
    "success_count": 790,
    "error_count": 10,
    "avg_latency_ms": 420.0
  },
  {
    "provider": "anthropic",
    "total_requests": 450,
    "total_tokens": 165000,
    "total_cost_usd": 3.95,
    "success_count": 440,
    "error_count": 10,
    "avg_latency_ms": 280.0
  }
]

Get Daily Usage ​

GET /api/settings/provider-keys/{tier}/usage/daily?days=30&provider=openai

Returns daily usage breakdown for trend analysis.

Response 200 OK

json
[
  {
    "date": "2026-02-09",
    "requests": 85,
    "tokens": 34000,
    "cost_usd": 0.92
  },
  {
    "date": "2026-02-08",
    "requests": 72,
    "tokens": 28500,
    "cost_usd": 0.78
  }
]

Supported Providers ​

LLM Providers ​

IDNameKey PrefixValidation Method
openaiOpenAIsk-GET /v1/models
anthropicAnthropicsk-ant-Anthropic GET /v1/models
geminiGoogle Gemini(none)GenAI SDK models.list()
bedrockAWS Bedrock(AWS access key)BYOK — models appear in picker when key is set
mistralMistral AI(none)OpenAI-compat GET /v1/models
cohereCohere(none)GET /v2/models
perplexityPerplexitypplx-OpenAI-compat GET /v1/models
xaixAI (Grok)xai-OpenAI-compat GET /v1/models
deepseekDeepSeeksk-OpenAI-compat GET /v1/models
groqGroqgsk_OpenAI-compat GET /v1/models
togetherTogether AI(none)OpenAI-compat GET /v1/models
openrouterOpenRoutersk-or-GET /models

Search Providers ​

IDNameKey PrefixValidation Method
tavilyTavilytvly-POST /search
braveBrave SearchBSAGET /web/search
serperSerper(none)POST /search

SOC 2 Type II Certified | BAA Available | HIPAA-Ready