Appearance
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
| Provider | Key Format | Get a Key | Description |
|---|---|---|---|
| OpenAI | sk-proj-... | platform.openai.com | GPT-4o, o3, DALL-E image generation |
| Anthropic | sk-ant-api03-... | console.anthropic.com | Claude Opus, Sonnet, and Haiku models |
| Google Gemini | AIza... | aistudio.google.com | Gemini 2.5 Pro/Flash, native image generation |
| Mistral AI | (varies) | console.mistral.ai | Mistral Large, Medium, Codestral |
| Cohere | (varies) | dashboard.cohere.com | Command R+, Embed models for RAG |
| Perplexity | pplx-... | perplexity.ai/settings | Sonar models with built-in web search |
| xAI (Grok) | xai-... | console.x.ai | Grok models with real-time knowledge |
| DeepSeek | sk-... | platform.deepseek.com | DeepSeek V3 and R1 reasoning models |
| Groq | gsk_... | console.groq.com | Ultra-fast LPU inference for Llama, Mixtral |
| Together AI | (varies) | api.together.xyz | Open-source model hosting with fine-tuning |
| OpenRouter | sk-or-v1-... | openrouter.ai/keys | Universal gateway to 200+ models |
| AWS Bedrock | Region + optional credentials | AWS Console | Use your own AWS account (BYOK). Claude, Titan, Llama, and more via Bedrock Runtime. |
Search Providers
| Provider | Key Format | Get a Key | Description |
|---|---|---|---|
| Tavily | tvly-... | tavily.com | AI-optimized web search API |
| Brave Search | BSA... | brave.com/search/api | Privacy-focused independent search |
| Serper | (varies) | serper.dev | Google 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
| Factor | Direct Route | OpenRouter Route |
|---|---|---|
| Latency | Lower | Higher |
| Cost | No markup | ~10–20% markup |
| Reliability | Single point | Aggregated fallback |
| Setup | API key required | Single 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 keysPlatform 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
| Scenario | Key Used | Why |
|---|---|---|
| You set an OpenAI key | Your key | User tier has highest priority |
| Org has OpenAI key, you don't | Org key | Falls through to tenant tier |
| Cloud admin locks OpenAI | Cloud key | Lock prevents all overrides |
| Org admin disables Tavily | None | Provider 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:
| Indicator | Meaning |
|---|---|
| No indicator | Key has no expiry set, or expiry is far away |
| Amber text | Key is expiring soon (within the reminder period) |
| Red text | Key has expired |
Rotation Workflow
- Set an expiry date when you add a new key
- GhostAI shows warnings as the expiry approaches
- Generate a new key at your provider
- Click Update Key on the provider card
- 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=30Usage & 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:
| Metric | Description |
|---|---|
| Requests | Total number of API calls |
| Tokens | Prompt + completion token counts |
| Estimated Cost | Approximate USD cost based on token pricing |
| Latency | Response time in milliseconds |
| Success/Error Rate | Count 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
| Tier | Who Can View | Scope |
|---|---|---|
| Cloud | Cloud admins | Platform-wide usage |
| Organization | Org admins | Organization-level usage |
| User | Any user | Personal 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:
| Tier | Managed | BYOK | Savings |
|---|---|---|---|
| Personal | $19/mo | $12/mo | 37% |
| Team | $29/user/mo | $17/user/mo | 41% |
| Business | $59/user/mo | $35/user/mo | 41% |
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.