Appearance
Managing Provider Keys
Overview
GhostAI uses a three-tier hierarchy for provider API key management. As an administrator, you can set platform defaults, organization shared keys, and control which providers are available to users. This guide covers key management for Cloud Admins and Organization Admins.
Role Requirements
- Cloud Admin — Manages platform-wide (cloud tier) keys. Requires the
cloud_adminorplatform_adminrole. - Organization Admin — Manages organization-level (tenant tier) keys. Requires the
adminorownerrole in the organization.
Cloud Admin
Setting Platform Default Keys
Cloud-tier keys serve as the default for all users and organizations on the platform. To configure them:
- Navigate to Settings > Provider Keys (Cloud Admin view)
- Click Set Key on the desired provider
- Paste the API key and optionally test it
- Click Save Key
Cloud keys are encrypted with PROVIDER_KEY_SECRET and stored in the database.
Platform Default Keys
Provider API keys configured in the environment (.env, Kubernetes Secrets, AWS Secrets Manager, etc.) are automatically registered as platform default keys on application startup. If no cloud-tier key exists for a provider, the environment value is stored in the database and labeled "Platform default". These keys are fully manageable through the admin UI — you can lock, disable, health-check, or replace them. Admin-set cloud keys are never overwritten.
Platform-wide Impact
When you set a cloud-tier key, it becomes the fallback for all users who don't have a personal or organization key configured. Ensure the key has adequate quota for platform-wide usage.
Cloud-Tier Actions
| Action | Effect | Who Is Affected |
|---|---|---|
| Set Key | Configure a default provider key | All users without org/personal keys |
| Update Key | Replace the existing key | Same as above |
| Remove Key | Delete the cloud key | Users fall back to org key or no key (re-registered as platform default on next restart if environment key still present) |
| Lock | Prevent lower tiers from overriding | All organizations and users |
| Unlock | Allow lower-tier overrides again | All organizations and users |
| Disable | Block a provider platform-wide | All organizations and users |
| Enable | Re-enable a disabled provider | All organizations and users |
| Health Check | Trigger immediate validation | N/A (diagnostic) |
Viewing All Provider Status
The Cloud Admin view shows all seventeen supported providers (14 LLM + 3 Search) with:
- Current status (Active / Not Set / Locked / Disabled)
- Health indicator (Healthy / Degraded / Unhealthy / Unknown)
- Masked key display (e.g.,
sk-proj...7x4q) - Last validation timestamp
- Quota bar (if provider reports usage)
- Consecutive failure count
Organization Admin
Setting Shared Organization Keys
Organization admins can set keys that all organization members share:
- Navigate to Settings > Provider Keys (Organization view)
- Click Set Key on the desired provider
- Paste the API key and test it
- Optionally check Lock key to prevent members from overriding
- Click Save Key
Organization keys are encrypted with the organization's Tenant Encryption Key (TEK) for Business/Enterprise tiers, providing cryptographic isolation from other organizations.
Cloud Locks Override
If a Cloud Admin has locked a provider, you cannot set or modify the organization key for that provider. The card will show a Locked badge with "(from Cloud)" indication.
Organization-Tier Actions
| Action | Effect | Who Is Affected |
|---|---|---|
| Set Key | Configure an org-wide provider key | All organization members |
| Update Key | Replace the existing org key | Same as above |
| Remove Key | Delete the org key | Members fall back to cloud key |
| Lock | Prevent members from using personal keys | All organization members |
| Unlock | Allow members to use personal keys | All organization members |
| Disable | Block a provider for the organization | All organization members |
| Enable | Re-enable a disabled provider | All organization members |
| Health Check | Trigger immediate validation | N/A (diagnostic) |
| View Audit | See key change history | N/A (informational) |
Feature Availability by Tier
Not all key management features are available on every subscription tier:
| Feature | Team | Business | Enterprise |
|---|---|---|---|
| Organization shared keys | Yes | Yes | Yes |
| Lock/Unlock | Yes | Yes | Yes |
| Disable/Enable | — | Yes | Yes |
| Audit trail | — | Yes | Yes |
| Health monitoring | Yes | Yes | Yes |
| Health history | — | Yes | Yes |
| TEK rotation | — | — | Yes |
| Cloud key admin | — | — | Yes |
Lock/Disable Controls
Locking a Provider
Locking a provider at a higher tier prevents all lower tiers from overriding the key:
Cloud Lock: Org admin CANNOT set org key
User CANNOT set personal key
→ Everyone uses the cloud key
Tenant Lock: User CANNOT set personal key
→ Org members use the org key
User tier: Cannot lock (no lower tiers)When to lock:
- You want to ensure all users use a specific key (e.g., for billing tracking)
- You need to enforce a rate-limited key for cost control
- Compliance requires using a specific API account
Disabling a Provider
Disabling a provider blocks all usage of that provider at the disabled tier and below:
Cloud Disable: Provider blocked for ENTIRE platform
No org or user can use this provider
Tenant Disable: Provider blocked for all org members
Other orgs and non-org users unaffectedWhen to disable:
- A provider has a security incident
- You want to restrict which AI providers are available
- A provider's terms of service conflict with your policies
Disable Is Immediate
Disabling a provider takes effect immediately — the resolve_key function checks the disabled flag on every chat request, so no new messages can use a disabled provider. Any in-flight requests will complete, but all subsequent requests are rejected.
Audit Trail
For Business and Enterprise tiers, every provider key operation is recorded in an immutable audit log.
Audited Actions
| Action | Description |
|---|---|
set | Key created or updated |
delete | Key removed |
lock | Key locked (prevents lower-tier override) |
unlock | Key unlocked |
disable | Provider disabled at this tier |
enable | Provider re-enabled |
Audit Entry Fields
| Field | Description |
|---|---|
| Timestamp | When the action occurred (ISO 8601) |
| Action | The operation performed |
| Provider | Which provider was affected |
| Actor | User ID of who performed the action |
| Details | JSON metadata (e.g., key prefix, lock flag) |
Accessing the Audit Trail
UI: The Organization Settings page shows a hint linking to the audit section.
API:
bash
GET /api/settings/provider-keys/organization/auditReturns the most recent 50 audit entries for the organization.
Health Dashboard
The Provider Keys tab includes real-time health information for each provider:
Health Indicators
| Indicator | Location | Description |
|---|---|---|
| Health dot | Provider card header | Green/amber/red/gray circle |
| Health message | Below card header | Short description (e.g., "Key valid") |
| Last check | Timestamps section | When the last check ran |
| Failure count | Below timestamps | Consecutive failures (if > 0) |
| Quota bar | Bottom of card | Visual remaining/total display |
Monitoring Schedule
| Tier | Frequency | Trigger |
|---|---|---|
| Cloud keys | Every 15 min | Automatic — APScheduler cron (*/15 * * * *) |
| Organization keys | Every 30 min | Automatic — APScheduler cron (*/30 * * * *) |
| User keys | Hourly (at :05 past) | Automatic — APScheduler cron (5 * * * *) |
| Any key | On-demand | Click "Check" button |
Alert Escalation
| Failures | What Happens |
|---|---|
| 1 | Status changes to unhealthy |
| 2 | In-app alert + email notification |
| 3+ | Critical log entry (cloud tier) |
| Recovery | Alerts auto-resolved |
Supported Providers
GhostAI supports 17 provider API keys across two categories:
LLM Providers
| Provider | ID | Key Prefix | Validation |
|---|---|---|---|
| OpenAI | openai | sk- | /v1/models |
| Anthropic | anthropic | sk-ant- | Anthropic /v1/models |
| Google Gemini | gemini | (none) | GenAI SDK models.list() |
| AWS Bedrock | bedrock | (AWS access key) | BYOK — models appear in picker when key is set |
| Microsoft Foundry | foundry | (JSON payload) | BYOK — endpoint + API key or Entra ID; models appear when key is set |
| Google Vertex AI | vertex | (JSON payload) | BYOK — project ID + region + service account JSON or ADC; models appear when key is set |
| Mistral AI | mistral | (none) | OpenAI-compat /v1/models |
| Cohere | cohere | (none) | /v2/models |
| Perplexity | perplexity | pplx- | OpenAI-compat /v1/models |
| xAI (Grok) | xai | xai- | OpenAI-compat /v1/models |
| DeepSeek | deepseek | sk- | OpenAI-compat /v1/models |
| Groq | groq | gsk_ | OpenAI-compat /v1/models |
| Together AI | together | (none) | OpenAI-compat /v1/models |
| OpenRouter | openrouter | sk-or- | /models |
Search Providers
| Provider | ID | Key Prefix | Validation |
|---|---|---|---|
| Tavily | tavily | tvly- | /search |
| Brave Search | brave | BSA | /web/search |
| Serper | serper | (none) | /search |
Each provider card in the UI includes a hover tooltip with a description and a direct "Get API key" link to the provider's key management page.
BYOK Providers (Bedrock, Foundry & Vertex)
AWS Bedrock, Microsoft Foundry, and Google Vertex AI use structured JSON key payloads instead of simple API key strings. When setting a key for these providers, the UI presents a custom form:
- AWS Bedrock — Region selector, optional access key + secret key, optional custom endpoint, PII referee toggle
- Microsoft Foundry — Endpoint URL, auth mode (API key or Entra ID), API key or tenant ID, PII referee toggle
- Google Vertex AI — GCP project ID, region dropdown, auth mode (Service Account or ADC), optional service account JSON upload, PII referee toggle
The JSON payload is validated before saving and encrypted at rest. All three providers support the same three-tier hierarchy (Cloud > Tenant > User) and all lock/disable/health features.
Key Rotation & Expiry Management
Admins can set expiry dates and rotation reminders on provider keys:
- Click Set Key or Update Key on a provider card
- In the Key Rotation section, set the expiry date and reminder period
- Optionally add a label (e.g., "Production Q1 2026")
- Save the key
Monitoring Expiring Keys
- Provider cards show amber/red expiry warnings
- Use the API to list all keys expiring within a period:bash
GET /api/settings/provider-keys/expiring?within_days=30 - Plan rotation before keys expire to avoid service interruption
Usage & Cost Visibility
The Provider Keys tab includes a collapsible Usage & Cost Tracking dashboard. Usage data is populated in real time — every chat message and search query that flows through a provider key calls record_usage, so the dashboard reflects actual platform activity.
Summary View
Six metric cards showing:
- Requests -- Total API calls in the period
- Tokens -- Total prompt + completion tokens
- Estimated Cost -- Approximate USD cost
- Successes -- Successful API calls
- Errors -- Failed API calls
- Avg Latency -- Mean response time
Per-Provider Breakdown
A table showing usage metrics broken down by provider, including request counts, token usage, cost, success/error rates, and average latency.
API Access
Usage data is available programmatically:
bash
# Summary for the organization tier
GET /api/settings/provider-keys/organization/usage/summary?days=30
# Per-provider breakdown
GET /api/settings/provider-keys/organization/usage/by-provider?days=30
# Daily usage trend
GET /api/settings/provider-keys/organization/usage/daily?days=30Best Practices
For Cloud Admins
- Set cloud keys for all essential providers — Ensures a fallback exists for all users
- Monitor health dashboard regularly — Catch quota issues before they impact users
- Lock providers only when necessary — Locking reduces user flexibility
- Rotate keys periodically — Limit the exposure window for any single key
- Configure email notifications — Set
CLOUD_ADMIN_EMAILto receive health alerts - Use dedicated API accounts — Don't share keys between GhostAI and other services
For Organization Admins
- Set org keys for providers your team uses — Centralizes billing and management
- Lock providers when billing control is important — Prevents members from using personal keys that bypass org billing
- Review the audit trail monthly — Ensure only authorized changes are made
- Test keys after setting them — The "Test before save" feature catches invalid keys immediately
- Watch for degraded health — Low quota warnings give you time to top up before outages
- Communicate changes to your team — Let members know when you lock, disable, or change keys
For Self-Hosted Deployments
- Back up
PROVIDER_KEY_SECRETsecurely — Encryption key for stored provider credentials. Generate withopenssl rand -hex 32. - Store
.envand database backups separately — Combined access enables decryption - Restrict file system access — Set
chmod 600on the.envfile - Plan for key rotation — Have a maintenance procedure for rotating
PROVIDER_KEY_SECRET - Monitor disk space — Health history logs grow over time (auto-purged after 90 days)