Bring Your Own Key

Heiryn supports a Bring Your Own Key (BYOK) system that lets you use your own API keys for AI providers. Keys can be set at the personal (account-wide) or community (server-wide) level.

Available Providers #

The provider list comes from the deployment's provider templates. ElevenLabs and OpenRouter are public by default, and deployments can add more providers or change their visibility. Providers may offer chat, image generation, transcription, or several capabilities. Public providers appear for everyone, private providers appear only for operators, and disabled providers are unavailable. Command autocomplete and the dashboard show the providers available to you.

Personal Keys #

Use /personal_provider_key to set a personal API key. This key applies to the capabilities offered by that provider, regardless of the server.

The provider option defaults to OpenRouter when omitted. Select elevenlabs explicitly to configure ElevenLabs transcription.

Personal keys take priority over community keys.

A personal key for the active chat provider also lets you choose a custom model from the provider catalog with /personal_chat_model or the dashboard. Deleting the key clears that custom model.

/personal_provider_key provider:openrouter api_key:sk-or-...
/personal_provider_key provider:elevenlabs api_key:sk_...

To check if a key is set, run the command without the api_key parameter. To delete a key, use - as the value.

Community Keys #

Use /community_provider_key to set a server-wide API key. This key is used for compatible interactions in the server unless the member has a usable personal key for that capability.

The provider option defaults to OpenRouter when omitted.

/community_provider_key provider:openrouter api_key:sk-or-... max_size:S
/community_provider_key provider:openrouter max_size:M
/community_provider_key provider:elevenlabs api_key:sk_...

The member who saves a community key becomes its owner. The key pays for every request it serves, so for the active chat provider only its owner can:

• change its maximum model category with max_size, without re-entering the key;
• choose any server chat model, beyond the category or as a custom model from the provider catalog.

Other server admins can still delete the key or replace it with their own, which makes them its owner. The owner needs the Manage Server permission to manage the key. Keys saved before ownership was recorded keep working with their category, but nobody can change that category until someone re-enters the key.

The max_size category controls what the key pays for beyond the server's default chat model (default: None):

• None: the key only pays for the server chat model, or Auto when none is set. Members who use a % suffix or a different personal model need their own key, and only the key owner can change the server chat model.
• XS to Z: members may also use models up to that size through suffixes and personal models, and any server admin may set a server chat model within that size. Auto is available to admins only when its default model fits.

Each regular chat category has base input and output price ceilings, documented under Models. Requests are only routed to providers priced within their alias category, but these per-token ceilings are not total request spending limits.

To check if a key is set, and who set it, run the command without the api_key parameter. To delete a key, use - as the value. Deleting or replacing the key clears a custom server chat model.

Requires the Manage Server permission.

Transcription Key Resolution #

Transcription providers are independent from the active chat provider. Keys are resolved by scope in this order:

1. Personal keys.
2. Community keys for the current server.
3. Deployment keys, for bot owners and allowlisted people or communities.

Within each scope, ElevenLabs is preferred and OpenRouter is the fallback. The resolver finishes the current scope before checking the next one. For example, a personal OpenRouter key takes priority over a community or deployment ElevenLabs key, while a community with only one OpenRouter key can continue to use both chat and transcription through OpenRouter.

This automatic provider choice happens only before a request. Heiryn does not retry with another provider after an authentication, credit, rate-limit, or transcription error. Use /personal_transcription_model, /community_transcription_model, or the dashboard to select a provider and model explicitly. An explicit selection is strict until it is cleared back to Auto.

ElevenLabs and OpenRouter #

Scribe v2 is available through both providers, but they are not equivalent:

Choose ElevenLabs when cleaned transcripts matter. Choose OpenRouter when one key should cover chat, images, and transcription. Auto mode makes this choice before the request, and an explicit provider/model selection is never replaced by the other provider.

Web Dashboard #

API keys can also be managed from the dashboard. The dashboard provides the same functionality as the slash commands with a visual interface for setting, checking, and removing keys.

If you opt out of the AI feature, your personal AI API keys are removed automatically.

Security #

All API keys are encrypted at rest.

Keys are never displayed in plain text after being set. The bot and the dashboard only confirm whether a key is present or absent.