Skip to content

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_admin or platform_admin role.
  • Organization Admin — Manages organization-level (tenant tier) keys. Requires the admin or owner role 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:

  1. Navigate to Settings > Provider Keys (Cloud Admin view)
  2. Click Set Key on the desired provider
  3. Paste the API key and optionally test it
  4. 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 ​

ActionEffectWho Is Affected
Set KeyConfigure a default provider keyAll users without org/personal keys
Update KeyReplace the existing keySame as above
Remove KeyDelete the cloud keyUsers fall back to org key or no key (re-registered as platform default on next restart if environment key still present)
LockPrevent lower tiers from overridingAll organizations and users
UnlockAllow lower-tier overrides againAll organizations and users
DisableBlock a provider platform-wideAll organizations and users
EnableRe-enable a disabled providerAll organizations and users
Health CheckTrigger immediate validationN/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:

  1. Navigate to Settings > Provider Keys (Organization view)
  2. Click Set Key on the desired provider
  3. Paste the API key and test it
  4. Optionally check Lock key to prevent members from overriding
  5. 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 ​

ActionEffectWho Is Affected
Set KeyConfigure an org-wide provider keyAll organization members
Update KeyReplace the existing org keySame as above
Remove KeyDelete the org keyMembers fall back to cloud key
LockPrevent members from using personal keysAll organization members
UnlockAllow members to use personal keysAll organization members
DisableBlock a provider for the organizationAll organization members
EnableRe-enable a disabled providerAll organization members
Health CheckTrigger immediate validationN/A (diagnostic)
View AuditSee key change historyN/A (informational)

Feature Availability by Tier ​

Not all key management features are available on every subscription tier:

FeatureTeamBusinessEnterprise
Organization shared keysYesYesYes
Lock/UnlockYesYesYes
Disable/Enable—YesYes
Audit trail—YesYes
Health monitoringYesYesYes
Health history—YesYes
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 unaffected

When 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 ​

ActionDescription
setKey created or updated
deleteKey removed
lockKey locked (prevents lower-tier override)
unlockKey unlocked
disableProvider disabled at this tier
enableProvider re-enabled

Audit Entry Fields ​

FieldDescription
TimestampWhen the action occurred (ISO 8601)
ActionThe operation performed
ProviderWhich provider was affected
ActorUser ID of who performed the action
DetailsJSON 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/audit

Returns 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 ​

IndicatorLocationDescription
Health dotProvider card headerGreen/amber/red/gray circle
Health messageBelow card headerShort description (e.g., "Key valid")
Last checkTimestamps sectionWhen the last check ran
Failure countBelow timestampsConsecutive failures (if > 0)
Quota barBottom of cardVisual remaining/total display

Monitoring Schedule ​

TierFrequencyTrigger
Cloud keysEvery 15 minAutomatic — APScheduler cron (*/15 * * * *)
Organization keysEvery 30 minAutomatic — APScheduler cron (*/30 * * * *)
User keysHourly (at :05 past)Automatic — APScheduler cron (5 * * * *)
Any keyOn-demandClick "Check" button

Alert Escalation ​

FailuresWhat Happens
1Status changes to unhealthy
2In-app alert + email notification
3+Critical log entry (cloud tier)
RecoveryAlerts auto-resolved

Supported Providers ​

GhostAI supports 17 provider API keys across two categories:

LLM Providers ​

ProviderIDKey PrefixValidation
OpenAIopenaisk-/v1/models
Anthropicanthropicsk-ant-Anthropic /v1/models
Google Geminigemini(none)GenAI SDK models.list()
AWS Bedrockbedrock(AWS access key)BYOK — models appear in picker when key is set
Microsoft Foundryfoundry(JSON payload)BYOK — endpoint + API key or Entra ID; models appear when key is set
Google Vertex AIvertex(JSON payload)BYOK — project ID + region + service account JSON or ADC; models appear when key is set
Mistral AImistral(none)OpenAI-compat /v1/models
Coherecohere(none)/v2/models
Perplexityperplexitypplx-OpenAI-compat /v1/models
xAI (Grok)xaixai-OpenAI-compat /v1/models
DeepSeekdeepseeksk-OpenAI-compat /v1/models
Groqgroqgsk_OpenAI-compat /v1/models
Together AItogether(none)OpenAI-compat /v1/models
OpenRouteropenroutersk-or-/models

Search Providers ​

ProviderIDKey PrefixValidation
Tavilytavilytvly-/search
Brave SearchbraveBSA/web/search
Serperserper(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:

  1. Click Set Key or Update Key on a provider card
  2. In the Key Rotation section, set the expiry date and reminder period
  3. Optionally add a label (e.g., "Production Q1 2026")
  4. 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=30

Best Practices ​

For Cloud Admins ​

  1. Set cloud keys for all essential providers — Ensures a fallback exists for all users
  2. Monitor health dashboard regularly — Catch quota issues before they impact users
  3. Lock providers only when necessary — Locking reduces user flexibility
  4. Rotate keys periodically — Limit the exposure window for any single key
  5. Configure email notifications — Set CLOUD_ADMIN_EMAIL to receive health alerts
  6. Use dedicated API accounts — Don't share keys between GhostAI and other services

For Organization Admins ​

  1. Set org keys for providers your team uses — Centralizes billing and management
  2. Lock providers when billing control is important — Prevents members from using personal keys that bypass org billing
  3. Review the audit trail monthly — Ensure only authorized changes are made
  4. Test keys after setting them — The "Test before save" feature catches invalid keys immediately
  5. Watch for degraded health — Low quota warnings give you time to top up before outages
  6. Communicate changes to your team — Let members know when you lock, disable, or change keys

For Self-Hosted Deployments ​

  1. Back up PROVIDER_KEY_SECRET securely — Encryption key for stored provider credentials. Generate with openssl rand -hex 32.
  2. Store .env and database backups separately — Combined access enables decryption
  3. Restrict file system access — Set chmod 600 on the .env file
  4. Plan for key rotation — Have a maintenance procedure for rotating PROVIDER_KEY_SECRET
  5. Monitor disk space — Health history logs grow over time (auto-purged after 90 days)

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