Setting Up BYOK Providers
Start your journey on the stage
Setting Up BYOK Providers
Bring Your Own Key (BYOK) lets you connect an AI provider account you control to RoleCall. You paste a provider API key, RoleCall stores it as an encrypted provider config, and your chats can route through that provider's models instead of only using RoleCall-hosted models.
Use BYOK when you want a specific provider, a specific model, your own provider billing, a custom OpenAI-compatible endpoint, or a provider needed by a scene system such as TTS.
You do not need BYOK to use RoleCall. RoleCall-hosted models appear automatically when your account has model access.
Where BYOK Lives
Open Settings -> API Keys.
Scroll to BYOK Providers and click + Add Provider.
BYOK Providers are your OpenAI, Anthropic, OpenRouter, Google, ElevenLabs, Custom endpoint, and other provider credentials. This is the section used by chat, model routing, and TTS.
If you do not see the provider form, finish the encryption setup prompt first. Provider configs cannot be saved until your account has an encryption key available.
Quick Setup
- Go to Settings -> API Keys.
- Scroll to BYOK Providers.
- Click + Add Provider.
- Pick the provider you want to connect.
- Choose an Encryption Mode.
- Paste the required credentials.
- Optionally enter a config name, model ID, base URL, headers, or body params.
- Click Fetch Models if you want to choose a model from the provider's model list.
- Save the configuration.
- Click Test Key on the saved provider card.
After the key is saved, the provider appears in model pickers under Your Providers. In a scene, open the model selector/Cast surface and choose the saved provider connection, then choose the model.
Encryption Modes
Each provider config has its own encryption mode. Pick the mode based on how the key needs to be used.
| Mode | What it means | Best for |
|---|---|---|
| Server-Accessible | The config is encrypted at rest with server-held encryption. RoleCall can decrypt it when a server-side job needs to make the provider request. | Group performance auto-responses, background systems, convenience, TTS routing, most users. |
| End-to-End Encrypted | The config is encrypted with your browser recovery key. RoleCall stores the encrypted blob but cannot decrypt it without your browser participating. | Maximum privacy for direct 1-on-1 use. |
The add-provider modal currently recommends Server-Accessible because some RoleCall features run server-side. If you choose End-to-End Encrypted, that key is appropriate for direct client-assisted use, but it cannot power jobs where the server must act without your browser supplying the decrypted credential.
Common rule:
- Solo scenes where you are actively present: E2E can work.
- Group auto-response, orchestration, background generation, and many voice/TTS flows: use Server-Accessible.
You can save multiple configs for the same provider. A practical setup is:
Anthropic Personalas E2E for private solo scenes.OpenRouter Group Fallbackas Server-Accessible for groups.ElevenLabs Voiceas Server-Accessible for TTS.
Provider Picker
The Add Provider picker is grouped by provider category.
| Category | Examples |
|---|---|
| Major Providers | OpenAI, Anthropic, OpenRouter, Google AI, RoleCall-hosted access |
| OpenAI Compatible | Mistral, Groq, Perplexity, DeepSeek, xAI, AI21, Fireworks, AIML API, NanoGPT, ElectronHub, CometAPI |
| Specialized | Cohere, NovelAI, ElevenLabs, Minimax |
| Enterprise | Azure OpenAI, Vertex AI |
| Regional | Moonshot, SiliconFlow, Z.AI |
| Free | Pollinations |
| Custom | Any reachable OpenAI-compatible endpoint |
Some entries are chat providers. Some are service providers. For example, ElevenLabs and Minimax are provider configs used by the voice/TTS system; they do not add chat models to the Cast picker.
Provider Fields
The form changes based on the selected provider. Required fields appear first. Advanced or provider-specific fields appear when relevant.
Common fields:
| Field | What it does |
|---|---|
| Config Name | A label shown in provider lists and model pickers. Use names like Personal, Group fallback, or Voice key. |
| API Key / API Token | The credential from the provider. |
| Service Account JSON | Vertex AI uses this instead of a normal API key. |
| Group ID | Minimax requires this for voice calls. |
| Base URL | Custom provider endpoint, or a proxy endpoint for providers that support overrides. |
| Model ID | Pins the config to a specific model. Leave blank if you want to choose models per scene. |
| Chat Completions URL | Custom-only override when RoleCall's endpoint auto-detection is wrong. |
| Models List URL | Custom-only override for model discovery. |
| Custom Headers | Extra HTTP headers, one key: value per line or a JSON object. |
| Custom Body Params | Extra request-body fields, one key: value per line or a JSON object. Useful for sampler values like min_p. |
| Endpoint Type | Provider-specific routing, such as NanoGPT plan type or Z.AI endpoint type. |
Provider credentials are saved as encrypted JSON. The plain key is not displayed back to you later; editing a config decrypts it in the browser or through the server-mode decrypt endpoint depending on the config mode.
Fetching Models
Most chat providers have a Model ID field. If RoleCall can query that provider's model list, the form shows Fetch Models or Refresh.
Use this when:
- You want a dropdown of models instead of typing a model ID.
- The provider recently added models and they are not showing yet.
- You are configuring a Custom endpoint and need to verify the models endpoint.
What happens:
- RoleCall sends a models-only request to the selected provider or endpoint.
- The returned model list is cached on your provider config.
- The Model ID field becomes a dropdown/search picker when models are available.
- Saving the config stores the selected default model ID and cached model list.
If a provider has no public models endpoint, RoleCall may use a static model list or require you to type the model ID manually.
Testing a Provider
After saving, click Test Key on the provider card.
The test checks whether RoleCall can use the saved provider config. A saved provider card can show:
| Status | Meaning |
|---|---|
| Valid | The last test succeeded. |
| Invalid | The provider rejected the config or could not be reached. |
| Not Tested | The config was saved but has not successfully tested yet. |
Common failures:
| Error | Usually means |
|---|---|
| 401 / Unauthorized | Wrong key, revoked key, or copied whitespace. |
| 403 / Forbidden | Key exists, but account/model permissions do not allow the request. |
| 404 / Not Found | Usually a wrong Custom Base URL, Chat Completions URL, or Models List URL. |
| 429 / Rate limit | Provider account is throttled or out of quota. |
| Connection error | Provider outage, blocked endpoint, or private/local URL that RoleCall cannot reach. |
For saved configs with a selected model, the edit modal may also show Test Tool Call. That checks whether the selected model/provider path can handle tool calling. This matters for systems that need structured actions, such as assistants, trackers, and compendium-style workers.
Using BYOK in Scenes
Once a provider is saved:
- Open a scene.
- Open the model selector/Cast surface.
- Look for Your Providers.
- Choose the saved provider config.
- Pick a model from that provider.
Saved provider configs appear as separate chips. If you save two OpenAI configs, they show as two separate connections, using the config names you gave them.
RoleCall-hosted models appear separately as RoleCall servers. Those do not require provider keys.
Custom OpenAI-Compatible Endpoints
Use Custom (OpenAI-Compatible) for proxies, self-hosted servers, or providers that speak the OpenAI chat-completions format but are not listed directly.
Required:
- A public Base URL, or explicit Chat Completions URL.
- An API key if your endpoint requires auth.
- A Model ID if the endpoint cannot return a model list.
Important: localhost, 127.0.0.1, and private LAN addresses do not work for production RoleCall requests. RoleCall's servers cannot reach your home computer's loopback address. If you want to use Ollama, LM Studio, vLLM, llama.cpp, KoboldCpp, TabbyAPI, or a similar local server, expose it through a real HTTPS endpoint first.
Common tunnel/proxy options include Cloudflare Tunnel, ngrok, Tailscale Funnel, or your own reverse proxy.
If auto-detection points at the wrong path, fill:
- Chat Completions URL with the exact chat endpoint.
- Models List URL with the exact models endpoint.
TTS Provider Keys
Voice systems use BYOK provider configs too.
| Provider | Used for | Notes |
|---|---|---|
| ElevenLabs | TTS and voice selection | Requires an ElevenLabs API key. |
| Minimax | TTS / voice provider support | Requires API key and Group ID. |
These configs are not chat model providers. They are stored in the same BYOK Providers section so the app has one encrypted provider registry instead of a separate place for every kind of credential.
If TTS needs to run from a server-side scene system, use Server-Accessible encryption.
Background Features and Group Chats
Some features are triggered by your browser. Other features run as server jobs.
Server-side features need a provider config the server can decrypt. That means Server-Accessible.
Use Server-Accessible for:
- Group performance auto-responses.
- Any orchestrator that picks speakers without you clicking every turn.
- Scheduled/background generation.
- Server-run compendium or tracker jobs that need a BYOK model.
- TTS flows that synthesize outside a direct browser-only action.
Use E2E for:
- Personal direct use where your browser can decrypt and supply the provider key for the request.
- Maximum privacy when you do not need background behavior.
If a group or background feature cannot use your E2E provider, add a second Server-Accessible provider config and select that for the feature.
Maintaining Provider Configs
Rotate a key
Open Settings -> API Keys -> BYOK Providers, click Edit, paste the new credential, then save and test.
Rename a connection
Open Edit and change Config Name. This changes the label in provider lists and model pickers.
Refresh a stale model list
Open Edit, click Refresh or Fetch Models, save, then test again.
Delete a connection
Click Delete on the provider card. This removes the encrypted provider config from your account. It does not revoke the key at the provider. Revoke keys from the provider's dashboard if you want them invalidated completely.
FAQ
Do I need BYOK to chat? No. RoleCall-hosted models work without BYOK when your account has access.
Why does the add-provider modal recommend Server-Accessible? Because many scene systems run server-side. Server-Accessible works for both direct use and background/group use. E2E is stricter privacy but narrower capability.
Can RoleCall see my E2E provider key? The stored config is encrypted with your browser recovery key. The server stores the encrypted blob. For an E2E-backed request, your browser must decrypt and provide the credential for the request path; background jobs cannot do that by themselves.
Can RoleCall see Server-Accessible provider keys? Server-Accessible configs are encrypted at rest, but RoleCall's server can decrypt them to make provider requests. Use this mode only for keys you are comfortable allowing server-side systems to use.
Can I have two configs for the same provider? Yes. Providers that allow multiple configs can be saved more than once. Name them clearly so the model picker is understandable.
Why did Test Key pass but generation still fails? The test may verify model listing or connection basics, while generation can still fail because of model permissions, account quota, context length, rate limits, or tool-call support.
Why do I not see models after saving? Open the config, click Fetch Models or Test Key, and save. Some providers also require a manually typed Model ID.
Can I use OpenRouter or NanoGPT as one key for many models? Yes. Router/aggregator providers expose many upstream models through one provider account. Leave Model ID blank if you want to pick models per scene, or choose a default model if you want that config to start on one model.
Can I use a local model? Yes, through Custom, but the endpoint must be reachable from RoleCall's servers over HTTPS. A URL on your own machine's localhost will not work in production.
Quick Reference
| Task | Where |
|---|---|
| Add a provider key | Settings -> API Keys -> BYOK Providers -> + Add Provider |
| Test a saved provider | Provider card -> Test Key |
| Edit credentials or default model | Provider card -> Edit |
| Refresh available models | Edit provider -> Fetch Models / Refresh |
| Delete a provider config | Provider card -> Delete |
| Pick a BYOK model in chat | Scene model selector -> Your Providers |
| Use a provider for group auto-response | Save/select a Server-Accessible provider config |
| Connect TTS | Add ElevenLabs or Minimax under BYOK Providers |
| Learn the broader provider system | Providers, BYOK & Encryption |