Appearance
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/cloudReturns 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/cloudSet Cloud Provider Key
PUT /api/settings/provider-keys/cloud/{provider}Set or update a provider key at the cloud tier.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
provider | string | Provider identifier (see Supported Providers below) |
Request Body:
json
{
"key": "sk-proj-abc123...",
"locked": false
}| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | The provider API key |
locked | boolean | No | Lock 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/openaiDelete 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/openaiTest Cloud Provider Key
POST /api/settings/provider-keys/cloud/{provider}/testValidate 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/organizationReturns 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/organizationSet 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:
| Status | Condition |
|---|---|
403 | Cloud tier has locked this provider |
403 | Cloud tier has disabled this provider |
403 | User is not an organization admin |
400 | Unsupported 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/openrouterDelete 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}/testSame 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/userReturns 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/userSet 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:
| Status | Condition |
|---|---|
403 | Cloud tier has locked this provider |
403 | Cloud tier has disabled this provider |
403 | Organization tier has locked this provider |
403 | Organization tier has disabled this provider |
400 | Unsupported 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/tavilyDelete 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}/testSame schema as cloud test endpoint.
Resolution Endpoint
Get Resolved Provider Keys
GET /api/settings/provider-keys/resolvedReturns 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/resolvedHealth Endpoints
Health endpoints require the key_health_monitoring feature flag (Team tier and above).
Get All Provider Health
GET /api/settings/provider-keys/healthReturns 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}/checkTrigger an immediate health check for a provider key at a specific tier.
Path Parameters:
| Parameter | Type | Values |
|---|---|---|
tier | string | cloud, tenant, user |
provider | string | Provider identifier |
Permissions:
| Tier | Required Role |
|---|---|
cloud | Cloud admin |
tenant | Organization admin |
user | Authenticated 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/checkGet Health History
GET /api/settings/provider-keys/health/{provider}/historyReturns 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/historyAudit Endpoint
Get Organization Key Audit
GET /api/settings/provider-keys/organization/auditReturns 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/auditError Responses
All endpoints return standard error responses:
| Status | Meaning |
|---|---|
400 | Bad request (unsupported provider, invalid input) |
401 | Not authenticated |
403 | Insufficient permissions (wrong role, locked/disabled provider) |
404 | Resource not found (no key at specified tier, no organization) |
500 | Internal 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}/expirySet or update the expiry date, rotation reminder, and label for a provider key.
Path Parameters:
| Parameter | Type | Values |
|---|---|---|
tier | string | cloud, organization, user |
provider | string | Provider identifier |
Request Body:
json
{
"expires_at": "2026-06-01T00:00:00Z",
"rotation_reminder_days": 90,
"label": "Production key Q2 2026"
}| Field | Type | Required | Description |
|---|---|---|---|
expires_at | string (ISO 8601) | No | When the key expires (null to clear) |
rotation_reminder_days | integer | No | Days before expiry to warn (default: 90) |
label | string | No | Friendly label for the key |
Response 200 OK -- Returns the updated ProviderKeyStatus object.
List Expiring Keys
GET /api/settings/provider-keys/expiring?within_days=30Returns all keys expiring within the specified number of days.
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
within_days | integer | 30 | Number 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=openaiReturns aggregate usage metrics for a tier.
Path Parameters:
| Parameter | Type | Values |
|---|---|---|
tier | string | cloud, organization, user |
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
days | integer | 30 | Lookback period in days |
provider | string | (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=30Returns 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=openaiReturns 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
| ID | Name | Key Prefix | Validation Method |
|---|---|---|---|
openai | OpenAI | sk- | GET /v1/models |
anthropic | Anthropic | sk-ant- | Anthropic GET /v1/models |
gemini | Google Gemini | (none) | GenAI SDK models.list() |
bedrock | AWS Bedrock | (AWS access key) | BYOK — models appear in picker when key is set |
mistral | Mistral AI | (none) | OpenAI-compat GET /v1/models |
cohere | Cohere | (none) | GET /v2/models |
perplexity | Perplexity | pplx- | OpenAI-compat GET /v1/models |
xai | xAI (Grok) | xai- | OpenAI-compat GET /v1/models |
deepseek | DeepSeek | sk- | OpenAI-compat GET /v1/models |
groq | Groq | gsk_ | OpenAI-compat GET /v1/models |
together | Together AI | (none) | OpenAI-compat GET /v1/models |
openrouter | OpenRouter | sk-or- | GET /models |
Search Providers
| ID | Name | Key Prefix | Validation Method |
|---|---|---|---|
tavily | Tavily | tvly- | POST /search |
brave | Brave Search | BSA | GET /web/search |
serper | Serper | (none) | POST /search |