Bring Your Own Key (BYOK)

Koji's Bring Your Own Key feature lets you connect your own API keys from AI providers instead of using Koji's built-in allocation. This gives you direct control over costs, access to your organization's negotiated rates, and the ability to use private or enterprise model deployments.

---

Who Is BYOK For

BYOK is designed for teams that:

• Want cost transparency. You see exactly what you spend on AI processing through your own provider dashboard.
• Have negotiated enterprise rates. If your organization has volume discounts with an AI provider, BYOK lets you take advantage of those rates.
• Need specific model access. If you have access to private or early-access models through your provider, BYOK lets Koji use those models.
• Require data residency controls. Using your own API key means AI requests flow through your provider account, giving you control over data processing regions.

---

Plan Requirements

BYOK is available on the Growth plan and above. If you are on the Starter plan, you use Koji's built-in AI allocation. Visit the plan comparison guide to see all plan features.

---

Setting Up BYOK

To connect your own API key:

1. Navigate to Account Settings > AI Provider Keys in the Koji dashboard.
2. Click Add Provider Key.
3. Select the AI provider from the dropdown.
4. Enter your API key.
5. Click Test Connection to verify the key works.
6. Click Save.

Once saved, Koji uses your key for all AI-powered features including interview conversations, analysis, and insight generation.

Testing the Connection

The Test Connection button sends a small validation request to the provider using your key. This confirms:

• The key is valid and not expired.
• The key has the necessary permissions.
• The provider is reachable.

If the test fails, double-check that you copied the full key and that it has not been revoked or restricted.

---

Supported Providers

Koji supports BYOK for the major AI providers. The available providers are shown in the dropdown when you add a new key. The platform automatically uses the appropriate models from your provider based on the task being performed.

---

How BYOK Affects Billing

When you use BYOK:

• Koji does not charge for AI processing. Your usage runs through your own provider account, and you pay the provider directly.
• Your Koji subscription still applies. Plan features like interview limits, team seats, and storage are still governed by your Koji plan.
• You monitor costs on the provider side. Use your AI provider's dashboard to track usage and spending.

This can be significantly more cost-effective for high-volume research teams, especially those with enterprise provider agreements.

---

Managing Your Keys

From the AI Provider Keys page, you can:

• View connected providers. See which providers have active keys.
• Test keys. Re-run the connection test at any time to verify keys are still valid.
• Remove keys. Delete a provider key to switch back to Koji's built-in allocation for that provider.
• Update keys. Replace an existing key if you need to rotate credentials.

When you remove a BYOK key, Koji automatically falls back to its built-in AI allocation (subject to your plan's included usage).

---

Key Security

Koji takes the security of your API keys seriously:

• Encrypted at rest. Keys are encrypted before being stored in the database.
• Encrypted in transit. Keys are transmitted over TLS and never sent in plain text.
• Masked in the UI. After saving, only the last four characters of your key are displayed.
• Access-controlled. Only account administrators can view or manage BYOK settings.
• Not logged. Your keys are never written to application logs.

Despite these protections, follow best practices for API key management:

• Use a dedicated key for Koji rather than sharing a key across multiple services.
• Set spending limits on the provider side to prevent unexpected charges.
• Rotate keys periodically.
• Monitor your provider dashboard for unusual usage patterns.

---

Troubleshooting

Key test fails with "invalid key"

Double-check that you copied the complete key with no extra spaces. Some providers include a prefix (like sk-) that must be included.

Key test fails with "insufficient permissions"

Your API key may be restricted to certain endpoints or models. Koji requires access to the models used for conversation and analysis. Check your provider's key permissions settings.

AI features slower than before

Performance depends on your provider account's rate limits and tier. If you are on a free or low-tier provider plan, requests may be throttled. Consider upgrading your provider plan for better performance.

Unexpected charges on provider account

Each interview and analysis pipeline makes multiple requests to the AI provider. Higher-volume research projects generate more requests. Set spending alerts on your provider account to stay informed.

---

BYOK and Project-Level API Keys

BYOK (your AI provider keys) and project API keys serve different purposes:

These two types of keys are independent. You can use BYOK without the API, and you can use the API without BYOK.

---

Next Steps

• Compare plans to confirm BYOK availability
• Manage your project API keys