Setting Up BYOK Providers
Start your journey on the stage
Setting Up BYOK Providers
Bring Your Own Key (BYOK) means connecting an external AI provider — OpenAI, Anthropic, Google, OpenRouter, and more than twenty others — using an API key you control. RoleCall routes your requests through it, and you pay the provider directly.
This guide walks through the full connection flow: picking a privacy mode, filling the fields, testing the key, and then using that provider's models in a scene.
1. What BYOK Is — and When to Use It
By default, RoleCall runs on its own hosted infrastructure — the Premiere Theater. No key required, no provider setup, no invoice from a third party. If you're happy with the Premiere Theater models and want zero friction, you can ignore BYOK entirely.
You'd reach for BYOK when:
- A specific model matters to you. A preset you love was tuned for Claude, or a workflow needs GPT-4's function calling, or you want DeepSeek Reasoner. BYOK gives you direct access to that exact model from the provider who runs it.
- You want control over spend. With BYOK you pay the provider directly, at their rates. Your RoleCall account limits don't apply.
- You want access to models not yet in the Premiere Theater. BYOK lets you connect new models as soon as the provider releases them — you don't have to wait for RoleCall to add them.
- You already have a provider subscription. If you're already paying for an OpenAI API plan or an Anthropic account, connecting it here is a natural extension.
If none of those apply, the Premiere Theater is the simpler path. See Providers & Keys for a full comparison.
2. Open Settings → API Keys Tab
Navigate to Settings from the main navigation. Click the API Keys tab — or go directly to /settings?tab=api-keys.
The page has several sections. Scroll down past the End-to-End Encryption cards and the Token Balance section until you see the heading BYOK PROVIDERS. That's where your provider configurations live.
Encryption must be set up first
Before you can save any provider key, RoleCall needs an encryption key on standby. Your provider key will be encrypted before it ever leaves your browser.
If you see a prompt in the BYOK Providers section asking you to complete encryption setup, do that first. Click through the setup flow, generate your 12-word phrase, write it down somewhere safe, and complete the type-back confirmation. Once the encryption status shows Active, come back to this section and the Add Provider button will be available.
If you already set up encryption at account creation, you won't see this prompt.
3. Click + Add Provider
Find the + Add Provider button in the BYOK Providers section and click it. The Add Provider modal opens.
The next few steps happen inside that modal. You don't need to save between them — the modal holds everything until you click Save.
Step 3a — Pick Your Privacy Mode
The first and most important decision is how your API key will be stored. Two modes are available, and you choose per provider config.
End-to-End Encryption (E2E)
Your key is encrypted inside your browser using a key derived from your 12-word recovery phrase. The server stores an opaque blob it cannot decrypt. Only your browser — on a device where you've entered your recovery phrase — can ever read the key.
Choose E2E when privacy is the priority: solo chats, providers with sensitive billing credentials, or any setup where you want a cryptographic guarantee that RoleCall's servers can't read your key.
One trade-off: E2E keys cannot be used by background jobs. Any feature that runs server-side — group auto-responders, scheduled regenerations, worker-based post-production passes — requires the server to decrypt your key to sign the outbound request. If your key is E2E-encrypted, those features will silently skip your provider. More on this at the end of the guide.
Server-Accessible
Your key is still encrypted at rest — but with a key the server holds rather than a key derived from your phrase. RoleCall can decrypt it on your behalf to make requests.
This mode is required for:
- Group chat auto-responders — when the orchestrator picks which character speaks next without you triggering each turn manually.
- Scheduled or background generation — any job that runs server-side without you actively in the scene.
Server-Accessible is slightly less private in the sense that RoleCall staff could, in principle, access the key. In practice, the keys are still encrypted at rest and not stored in plaintext anywhere. The privacy difference is meaningful only if you're specifically worried about server-side access.
A common pattern is to keep your most sensitive keys as E2E (direct Anthropic or OpenAI keys) and add one Server-Accessible config — often OpenRouter, since it routes many models through one key — as the group-friendly fallback.
Pick your mode now, before filling in anything else. It's set per config and can't be changed after saving without deleting and recreating the config.
Step 3b — Choose a Provider
The modal has a dropdown (or picker) for provider type. RoleCall ships with adapters for more than twenty-five providers across several categories:
Major providers: OpenAI, Anthropic, OpenRouter, Google AI (Gemini)
OpenAI-compatible: Mistral AI, Groq, Perplexity, DeepSeek, xAI (Grok), AI21, Fireworks AI, AIML API, NanoGPT, ElectronHub, CometAPI
Specialized: Cohere, NovelAI
Enterprise: Azure OpenAI, Vertex AI (Google Cloud)
Regional: Moonshot (Kimi), SiliconFlow, Z.AI (Zhipu)
Free: Pollinations (no key required)
Custom: Any OpenAI-compatible endpoint — self-hosted models (Ollama, LM Studio, llama.cpp, vLLM, KoboldCpp, TabbyAPI), proxies, or services not in the list above.
Selecting a provider pre-fills the base URL and shows you only the fields that provider actually needs. You won't see Azure's Deployment ID fields when you're setting up Anthropic.
Step 3c — Label the Config
Give this provider config a display name. This label appears in the model picker inside every scene and in your provider list here. It's for you — the AI doesn't see it.
You can save multiple configs per provider. Reasons to do this:
- Two OpenAI keys, one personal and one for a shared organization.
- A direct Anthropic key labeled "Anthropic personal" and an OpenRouter key labeled "OpenRouter fallback (group-safe)".
- Multiple Custom configs for different self-hosted servers: "Home Ollama" and "Cloud vLLM".
Label them so you can tell them apart at a glance.
Step 3d — Paste the API Key
Paste your API key into the key field. Most providers issue keys with a recognizable prefix:
| Provider | Key prefix |
|---|---|
| OpenAI | sk-... |
| Anthropic | sk-ant-... |
| OpenRouter | sk-or-... |
| Groq | gsk_... |
| Perplexity | pplx-... |
| Google AI | AIza... |
If you don't have a key yet, here's where to get one for the most common providers:
- OpenAI: platform.openai.com/api-keys
- Anthropic: console.anthropic.com → API Keys
- Google AI (Gemini): aistudio.google.com → Get API Key
- OpenRouter: openrouter.ai/keys
- Groq: console.groq.com/keys
For other providers, look for an "API Keys" or "Developer" section in their dashboard.
Step 3e — Optional Fields
Advanced options are typically behind an Advanced toggle. You won't need most of these for a standard setup, but they're useful in specific situations.
| Field | When to use it |
|---|---|
| Custom Base URL | You're routing through a proxy in front of the provider. Paste the proxy's base URL here. |
| Organization ID | OpenAI-only. Bills usage to a specific organization rather than your personal account. Useful if you're connecting a work or shared key. |
| Custom Headers | A reverse proxy requires an extra HTTP header on every request (e.g. x-proxy-secret: ...). Enter as key: value, one per line, or paste a JSON object. |
| Custom Body Params | Sampler values your preset needs that aren't in the standard UI (e.g. min_p: 0.1, top_k: 50). Same format: key: value per line, or JSON. |
| Endpoint Type | Provider-specific. NanoGPT lets you choose Pay-per-use vs Subscription; Z.AI lets you choose Common vs Coding. |
| Model ID | Pin this config to a specific model. Leave it blank if you want to pick per-scene. Pinning is useful when you always use the same model from a given key — it skips the picker. |
For Azure OpenAI and Vertex AI specifically, there are additional required fields (Resource Name, Deployment ID, API Version for Azure; Service Account JSON and Region for Vertex). The modal shows them when you select those providers.
4. Test the Key
Before saving, click the Test button. RoleCall sends a request to the provider's models-list endpoint using your key and reports back immediately.
| Result | What it means |
|---|---|
| Valid (green) | The key works. The provider returned a model list. You're good. |
| Invalid (red) | Something is wrong — see common errors below. |
| Not Tested (grey) | You saved without testing. Happens after editing a saved config. |
Testing also caches the provider's model list so the model picker populates quickly in scenes.
Common test errors and what they mean
401 Unauthorized / Invalid API key: The key you pasted is wrong or has been revoked. Double-check the copy-paste — no leading or trailing spaces.
403 Forbidden: The key exists but doesn't have access to the endpoint you're targeting. Some provider accounts have restricted permissions; check your provider's dashboard.
404 Not Found (Custom provider): The Base URL you entered likely points at the wrong path. Try appending /v1 or /api/v1 explicitly if auto-detection failed.
429 Too Many Requests: Your key's rate limit was hit during the test. Wait a moment and try again. This doesn't mean the key is invalid.
503 / Connection error: The provider is down or unreachable. Not a key problem — wait and try again.
5. Save
Click Save (or Add Provider). The modal closes and your new provider config appears in the BYOK Providers list with a status pill: Valid, Invalid, or Untested.
If you forgot to test before saving, you'll see Untested in grey. You can test any saved config at any time from the config card in the list — find your provider row and click Test Key.
6. Pick a Model in a Scene
Open any scene (or start a new one). In the Cast model picker — accessible from the AI wing on the right rail inside the scene — you'll now see your new provider's models listed alongside the Premiere Theater models.
The model picker is organized by provider. Each provider section shows the models available under that config. Each model row shows:
- Model name and ID
- Context window (8K, 32K, 128K, 1M, etc.)
- Capability badges: vision, tools, JSON mode, web search (where applicable)
- Speed indicator: Instant, Fast, or Deep
- Free indicator for models without a per-token cost
Use the search bar at the top to filter by name. Typing sonnet filters across every provider to show every Sonnet model you have access to. You can also star any model to pin it to the top of the picker.
Click a model to select it for the current scene. The generation starts using that model immediately — no restart needed.
The Cast page (outside a scene)
You can also browse and manage all your connected providers and their models from the Cast tab in Settings (/models). This is the same model library, just outside of a live scene.
7. Model Picker — What You See After Connecting
Once your provider is saved and tested, here is what changes across the interface.
In the Cast (Settings → /models)
The Cast page at /models is the standalone model browser, accessible from the Cast tab in Settings. After connecting a provider, a new section appears for that provider showing every model available under your key. Each model row shows:
- The model's display name and technical ID
- Context window size
- Any capability badges (vision, tool use, JSON mode, web search)
- A speed indicator (Instant, Fast, or Deep) based on the model family
You can star any model here to pin it to the top of every picker going forward.
In the AI Wing (Inside a Live Scene)
The AI wing on the right rail inside any scene is the same model picker in context. Your newly added provider shows up there alongside the Premiere Theater section. Click any model row to switch the active scene to that model immediately.
If you have many providers configured, the wing shows each one as a collapsible section labeled with your config's display name. Expand a section to see its models; collapse it to keep things tidy. The wing also has a search bar at the top — type any part of a model name to filter across all connected providers at once.
Once you have multiple providers connected, you can configure fallback behavior in your preset's API Options card.
Set a primary model. Then add one or more fallback models from any configured provider. If the primary model returns an error — the provider is down, your key rate-limits, the model is at capacity — RoleCall automatically moves to the next model in the fallback chain and retries the same turn.
Fallbacks work silently. You see the generation complete; you don't see the retry unless you look at the usage log.
A practical fallback chain example:
- Primary: your direct Anthropic key (E2E, best privacy)
- Fallback: OpenRouter pointing at the same model family (Server-Accessible, group-safe)
- Fallback: a Premiere Theater model (always available, no key needed)
8. Maintenance Tips
Rotating keys
When you rotate a key at the provider side (a good security practice), come back to Settings → API Keys → BYOK Providers, find the config, click Edit, paste the new key, and test it. The config stays in place — you're just replacing the credential.
Re-testing after breaks
Provider keys can expire, billing can lapse, and models can be deprecated. If you come back to a config you haven't used in a while and generation starts failing, click Test Key on that config. It'll tell you immediately whether the key is still valid.
What "Invalid (red)" means
A red Invalid pill means the last test (or a live generation attempt) returned an auth error from the provider. Common causes:
- The key was revoked from the provider's dashboard.
- Your billing at the provider has lapsed (no active payment method, quota exhausted).
- The key was correct but the trial period ended.
Fix by logging into the provider's dashboard, checking your key and billing status, and issuing a new key if needed. Then update the config here.
When the model list goes stale
Providers add and remove models. The model list in RoleCall is cached from the last time you tested the key. If you know a provider released a new model but it's not showing in the picker, click Test Key again — that re-fetches the model list and refreshes the cache.
9. Privacy Reminder — E2E Keys and Background Jobs
End-to-end encrypted keys cannot be decrypted server-side. That means they cannot be used for any generation that runs in the background without you actively in the scene:
- Group chat auto-responders (the orchestrator sends turns without you clicking Send)
- Scheduled post-production passes
- Worker-based background generation jobs
If you try to use an E2E key for one of these features, the request will fail because the server can't sign it. The fix is to add a second config for the same provider in Server-Accessible mode and use that config for group chats or background features.
This is a design trade-off, not a bug. E2E encryption specifically prevents server-side access to your key — background jobs are server-side operations. If you need both maximum privacy and background features, use E2E for your personal solo chats and Server-Accessible for the group or background config.
10. Common Questions
"Do I have to use BYOK? Can I just use RoleCall's models?" You don't have to. The Premiere Theater is fully functional with no API key setup. BYOK is optional — add it when you have a specific reason (a model you need, a budget you want to control, a provider you already pay for).
"I added a provider but I don't see any models in the picker." The model list is populated when you test the key. If you saved without testing, go back to Settings → API Keys → BYOK Providers, find the config, and click Test Key. After a successful test, the models appear in the picker inside any scene.
"The test passed but generation is failing in the actual scene." The Test Key check hits the provider's models-list endpoint, not a generation endpoint. A few things can pass the test but fail in generation:
- Your account doesn't have access to the specific model you're trying to use (some models require an elevated API tier at the provider).
- The provider has a different rate limit on generation vs. the models endpoint.
- The context you're sending is larger than the model's limit.
Check your provider's dashboard for any access restrictions on the specific model, and try a different model from the same provider to narrow it down.
"Can I share a provider config with other users?" No. Provider configs are personal — they hold your encrypted API key and are tied to your account. If a friend wants to use the same provider, they connect their own key under their own account.
"I set up E2E encryption for my key but group chat isn't working." E2E-encrypted keys can't be used by server-side jobs, including group auto-responders. Add a second config for the same provider (or any provider) in Server-Accessible mode and use that config when running group chats. Keep the E2E config for solo scenes.
"My key worked last week but now says Invalid." Most common causes: billing lapsed at the provider (check your invoice), the key was rotated or revoked from the provider's dashboard, or the model you had pinned was deprecated. Log into the provider's dashboard, verify your billing and keys, and then come back to Settings and either update the key or issue a new one.
"Can I use a local model (Ollama, LM Studio) with RoleCall?"
Yes, via the Custom (OpenAI-Compatible) provider type — but the endpoint needs a public address, not localhost. Every AI request runs server-side on RoleCall's infrastructure, so when those servers try to resolve localhost:11434, they hit their own loopback, not your machine. There's no network path from RoleCall's servers to your home network. Expose your local model with Cloudflare Tunnel, ngrok, Tailscale Funnel, or a public reverse proxy, and paste the public HTTPS URL (e.g. https://my-llm.trycloudflare.com) into Base URL.
"I don't see the 'Add Provider' button." Encryption must be set up before you can save provider keys. If you haven't completed the recovery-phrase setup, the BYOK Providers section shows a prompt asking you to do that first. Click through the encryption setup (it takes two minutes), and the Add Provider button will appear once encryption is active.
"Can I use OpenRouter to access models from multiple vendors through one key?"
Yes. OpenRouter is one of the most popular BYOK choices precisely because one key gives you access to models from many vendors — Anthropic, OpenAI, Google, Meta, Mistral, and more — all through a single connection. Model IDs use the format vendor/model-name (e.g. anthropic/claude-3-opus, openai/gpt-4-turbo). Leave the Model ID field blank in the config and you'll be able to pick any of their available models per-scene from the Cast picker.
"Premiere Theater is slow today. Can I switch to BYOK mid-scene?" Yes. Open the AI wing from the right rail, find your connected provider's section, and click the model you want. The switch takes effect immediately — the next message you send goes through that provider. You don't need to start a new scene or close anything.
Quick Reference
| Want to… | Where it is |
|---|---|
| Add a new provider | Settings → API Keys tab → BYOK Providers → + Add Provider |
| Test an existing provider key | Settings → API Keys tab → find the config card → Test Key |
| Change a key's label or credentials | Config card → Edit |
| Pick a model in a live scene | Right rail → AI wing → model picker |
| Browse all connected models outside a scene | Settings → Cast tab (/models) |
| Set a fallback chain | Preset editor → API Options card → fallback slots |
| Learn about encryption modes | Providers & Keys |
| Use the Premiere Theater instead | Providers & Keys — no setup needed |