API keys
These are the keys Mesa uses to call a model provider on your behalf. Without one, a bot is configured but cannot answer.
Keys are managed in the admin console, under Keys. The web app's Settings screen is not built yet, so there is nowhere else to do this — see The web app.
Which providers
| Provider | |
|---|---|
| OpenAI | Supported |
| Anthropic | Supported |
| A private-LLM provider | Only on deployments that enable it, and for a specific purpose — see below |
Anything else is rejected when you try to save it. In particular there is no Google/Gemini support, despite older documentation saying otherwise.
Global and BYOK
| Type | Meaning |
|---|---|
| Global | A key the deployment provides, shared by whatever falls under its scope |
| BYOK | Bring your own key — your own provider account, and your own bill |
Scopes and which key wins
A key is attached to a scope: a tenant, a bot group, a single bot, or a user. When a bot needs a key, Mesa walks the scopes from most specific to least, and within each scope prefers BYOK over global:
bot BYOK → bot global → tenant BYOK → tenant global
The first match is used. So a bot-level BYOK key overrides the tenant's shared key without changing anything about the tenant. The exact scope order is itself configurable per tenant, but the BYOK-before-global preference within a scope is fixed.
Private-LLM keys
Deployments that enable it use a separate provider for work that should not go to the main model vendor. Keys for it are user-scoped, and you may only create one for yourself — attempting to create a user-scoped key for somebody else is refused, because it would route their private data through an account they do not control.
Validation
A key is checked against the provider when you add it, and again whenever someone asks for a
re-check. It is not on a schedule: a key revoked at the provider will keep showing as active
here until something tries to use it or you re-validate it.
| Status | Meaning |
|---|---|
active | Last check passed |
invalid | Last check failed — the reason is recorded alongside |
expired | Past the expiry date you set when adding it |
How keys are stored
- Encrypted before storage, using envelope encryption: the key is encrypted with a data key, and the data key is itself wrapped by the deployment's key-management service.
- Never returned by the API — not even partially. What comes back is metadata only: scope, provider, type, status and dates. No endpoint hands back the key or any fragment of it.
- Never written to logs. Request bodies are redacted.
If you lose a key, replace it at the provider and add the new one. Mesa cannot show you the old one.