Skip to content

Bring Your Own API Key (BYOK) ​

Overview ​

GhostAI supports Bring Your Own Key (BYOK), allowing you to connect your personal API keys for AI and search providers. When you add your own key, GhostAI uses it for requests instead of the platform default — giving you control over your usage, billing, and quota.

BYOK is available on all subscription tiers, including Starter (free). BYOK customers receive a 37–41% discount on subscription pricing.

How BYOK Works

When you provide your own API key, GhostAI encrypts it at rest using industry-standard symmetric encryption before storing it. Your key is decrypted only in memory at the moment of use and is never written to logs or error messages.

Supported Providers ​

LLM Providers ​

ProviderKey FormatGet a KeyDescription
OpenAIsk-proj-...platform.openai.comGPT-4o, o3, DALL-E image generation
Anthropicsk-ant-api03-...console.anthropic.comClaude Opus, Sonnet, and Haiku models
Google GeminiAIza...aistudio.google.comGemini 2.5 Pro/Flash, native image generation
Mistral AI(varies)console.mistral.aiMistral Large, Medium, Codestral
Cohere(varies)dashboard.cohere.comCommand R+, Embed models for RAG
Perplexitypplx-...perplexity.ai/settingsSonar models with built-in web search
xAI (Grok)xai-...console.x.aiGrok models with real-time knowledge
DeepSeeksk-...platform.deepseek.comDeepSeek V3 and R1 reasoning models
Groqgsk_...console.groq.comUltra-fast LPU inference for Llama, Mixtral
Together AI(varies)api.together.xyzOpen-source model hosting with fine-tuning
OpenRoutersk-or-v1-...openrouter.ai/keysUniversal gateway to 200+ models
AWS BedrockRegion + optional credentialsAWS ConsoleUse your own AWS account (BYOK). Claude, Titan, Llama, and more via Bedrock Runtime.

Search Providers ​

ProviderKey FormatGet a KeyDescription
Tavilytvly-...tavily.comAI-optimized web search API
Brave SearchBSA...brave.com/search/apiPrivacy-focused independent search
Serper(varies)serper.devGoogle Search results API

Provider Tooltips

Hover over the info icon next to any provider name in the UI for a description of what it does and a direct link to get your API key.

How to Add Your Key ​

Step 1: Navigate to Settings ​

Open the Settings panel and select the Provider Keys tab. If you're a member of an organization, you'll see the Personal scope.

Step 2: Choose a Provider ​

Click Set Key on the provider card you want to configure (e.g., OpenAI).

Step 3: Enter Your API Key ​

Paste your API key into the input field. The field is masked by default — click the eye icon to reveal the key.

Test Before You Save

Click Test before save to validate your key against the provider's API. GhostAI makes a lightweight request (e.g., listing models) to confirm the key works.

Step 4: Save ​

Click Save Key. Your key is immediately encrypted and stored. GhostAI will use it for all subsequent requests to that provider.

Step 5: Verify ​

After saving, you'll see:

  • Active badge on the provider card
  • Key configured with a masked display (e.g., sk-proj...7x4q)
  • Source: User indicating the key is from your personal tier

How BYOK Enables Direct Routes ​

Adding your own API key for a provider unlocks direct routing for that provider's models. For example, adding an OpenAI key enables gpt-4o via a direct route to OpenAI's API — with lower latency and no markup on top of OpenAI's published pricing.

You can set a route preference per BYOK key. When multiple routes are available for a model (e.g., OpenAI direct vs OpenRouter), your preference determines which path is used. If the preferred route is unavailable (e.g., key missing or unhealthy), the system falls back to alternative routes for the same model, then to the primary provider.

Direct vs OpenRouter ​

FactorDirect RouteOpenRouter Route
LatencyLowerHigher
CostNo markup~10–20% markup
ReliabilitySingle pointAggregated fallback
SetupAPI key requiredSingle key for all

Direct routes require a configured API key for each provider. OpenRouter provides access to 200+ models with a single key, at the cost of added latency and markup.

Key Resolution ​

GhostAI uses a multi-tier resolution system. When making an API call, the system checks for keys in this order:

1. Your personal key (User tier)     ← Highest priority
2. Organization shared key (Tenant)
3. Platform default (Cloud tier)     ← Includes environment-provisioned keys

Platform defaults: Keys configured in the environment (.env, Kubernetes Secrets, AWS Secrets Manager) are automatically registered as platform default keys on startup (if no cloud-tier key already exists for that provider). These keys appear in the Platform Admin UI and are fully manageable — they can be locked, disabled, or replaced like any other cloud-tier key.

Your personal key always takes priority — unless an administrator has locked the provider at a higher tier. The key resolution function (resolve_key) enforces locks at request time: a locked cloud-tier key is used for every API call regardless of organization or personal keys.

Locked Providers

If your organization or platform admin has locked a provider, the lock is enforced both in the UI (the "Set Key" button is disabled and a Locked badge appears) and at the API layer (chat requests always use the locked tier's key).

Resolution Examples ​

ScenarioKey UsedWhy
You set an OpenAI keyYour keyUser tier has highest priority
Org has OpenAI key, you don'tOrg keyFalls through to tenant tier
Cloud admin locks OpenAICloud keyLock prevents all overrides
Org admin disables TavilyNoneProvider disabled for your org

Security ​

Your API keys are protected by multiple layers:

  • Encrypted at rest — Industry-standard symmetric encryption
  • Encrypted in transit — TLS 1.2+ for all provider API calls
  • Memory-only decryption — Keys are decrypted only at the moment of use, never cached
  • No logging — Key values never appear in logs, traces, or error messages
  • Display masking — Only the first 8 and last 4 characters are shown (e.g., sk-proj...7x4q)
  • Audit trail — All key operations are logged (set, update, delete)
  • Secrets detection — If you accidentally paste a key in chat, GhostAI's PII detector can catch it

Your Key, Your Billing

When you use your own API key, all usage is billed directly to your account at the provider. GhostAI does not charge extra for BYOK usage.

Admin Controls ​

Organization Admins (Team tier and above) ​

Organization admins can:

  • Set shared organization keys that all members use by default
  • Lock a provider to prevent members from using personal keys
  • Disable a provider to block it entirely for the organization
  • View the audit trail of key changes

Cloud Admins (Platform level) ​

Cloud admins can:

  • Set platform-wide default keys for all organizations and users
  • Lock a provider globally (no org or user can override)
  • Disable a provider platform-wide
  • Monitor health status of all provider keys

Key Rotation & Expiry ​

GhostAI supports key rotation tracking to help you manage API key lifecycles.

Setting an Expiry Date ​

When adding or updating a key, you can optionally set:

  • Expiry date -- When the key expires or should be rotated
  • Reminder period -- How many days before expiry to start showing warnings (default: 90 days)
  • Label -- A friendly name for the key (e.g., "Production key", "Team key")

Expiry Warnings ​

Provider cards show expiry status with color-coded indicators:

IndicatorMeaning
No indicatorKey has no expiry set, or expiry is far away
Amber textKey is expiring soon (within the reminder period)
Red textKey has expired

Rotation Workflow ​

  1. Set an expiry date when you add a new key
  2. GhostAI shows warnings as the expiry approaches
  3. Generate a new key at your provider
  4. Click Update Key on the provider card
  5. The rotation timestamp and expiry are automatically updated

Expiry API

Admins can also query expiring keys programmatically:

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

Usage & Cost Tracking ​

GhostAI records usage data for every API request routed through a provider key. Each chat message, search query, or model call that uses a BYOK key is tracked in real time via record_usage, giving you full visibility into cost and performance.

What's Tracked ​

Every API request through a provider key records:

MetricDescription
RequestsTotal number of API calls
TokensPrompt + completion token counts
Estimated CostApproximate USD cost based on token pricing
LatencyResponse time in milliseconds
Success/Error RateCount of successful vs failed requests

Viewing Usage ​

Open the Usage & Cost Tracking section at the bottom of the Provider Keys tab to see:

  • Summary cards -- Total requests, tokens, cost, success/error counts, and average latency
  • Per-provider breakdown -- Table showing usage metrics for each provider
  • Period -- Data covers the last 30 days by default

Usage by Tier ​

TierWho Can ViewScope
CloudCloud adminsPlatform-wide usage
OrganizationOrg adminsOrganization-level usage
UserAny userPersonal key usage

Usage Data Retention

Usage data is retained indefinitely. Cost estimates are approximations based on published provider pricing and may not exactly match your provider invoice.

BYOK Pricing ​

BYOK customers get a 37–41% discount compared to managed (platform-key) pricing:

TierManagedBYOKSavings
Personal$19/mo$12/mo37%
Team$29/user/mo$17/user/mo41%
Business$59/user/mo$35/user/mo41%

Starter (free) and Enterprise (custom) tiers are unaffected by BYOK pricing.

FAQ ​

Can I use different keys for different providers? ​

Yes. Each provider has its own key slot. You can set an OpenAI key, an OpenRouter key, and a Tavily key simultaneously, each from a different account.

What happens if my key expires or is revoked? ​

GhostAI's health monitoring detects the issue automatically — scheduled checks run every 15 minutes for cloud keys, every 30 minutes for organization keys, and hourly for personal keys. The provider card shows an Unhealthy status, and the system falls back to the next available tier (organization or cloud key) automatically. You'll see a notification prompting you to update your key.

Can my organization admin see my personal key? ​

No. Your key value is encrypted and never exposed — not even to admins. Admins can only see that you have a key configured (with a masked display like sk-proj...7x4q).

How do I remove my key? ​

Click Remove on the provider card. This permanently deletes your encrypted key. GhostAI will fall back to the organization or cloud key for future requests.

Is BYOK available on the Starter tier? ​

Yes. All users on all tiers can bring their own keys. This is especially useful on the Starter tier where platform-provided quota may be limited.

What if I'm in an organization that locks a provider? ​

You'll see a Locked badge on the provider card. The "Set Key" button will be disabled. Contact your organization admin if you need to use a personal key for a locked provider.

Are my keys safe if the database is breached? ​

Yes. The database contains only encrypted ciphertext. The encryption key is stored separately from the database in a secure server-side location. An attacker who obtains only the database cannot decrypt your keys.

How do I set up key rotation reminders? ​

When adding or updating a key, expand the Key Rotation section in the modal. Set an expiry date and reminder period. GhostAI will show amber warnings on the provider card as the expiry approaches and red warnings after expiry.

Can I see how much each provider key costs? ​

Yes. Open the Usage & Cost Tracking section at the bottom of the Provider Keys tab. It shows per-provider cost estimates based on token usage over the last 30 days.

What providers support direct API keys? ​

GhostAI supports 15 direct providers: OpenAI, Anthropic, Google Gemini, Mistral AI, Cohere, Perplexity, xAI (Grok), DeepSeek, Groq, Together AI, OpenRouter, and AWS Bedrock for LLMs, plus Tavily, Brave Search, and Serper for web search. OpenRouter also provides access to 200+ models from all major providers with a single key. AWS Bedrock BYOK lets you use your own AWS account and region for Claude, Titan, Llama, and other Bedrock models.

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