# AI & API Keys

## Overview

The AI & API Keys page holds the platform owner's global AI provider keys. Every AI feature — the AI chatbot, reply suggestions, content generation, the voice assistant — runs on a key set either here or in a customer's own workspace settings. This page is the platform-level fallback that keeps those features working for every customer who hasn't supplied their own key.

Find it in the admin sidebar under Admin → AI / API keys. All five supported providers are already listed as cards, so there is no "install" step. You simply paste a key, fill any optional fields, pick a default model, click Save, and flip the card to Active.

On each card you can:

- Save the API key, default model, display order, and any optional fields that provider offers.
- Activate or deactivate the provider (you must save a key before you can activate — see below).

> Note: On a brand-new install the five provider cards appear automatically. If your support team ever needs to restore them, ask them to re-run the install setup — it never overwrites a key or default you have already saved.

## Supported Providers

WaDesk supports five AI providers, one card each. Each card shows only the fields that vendor actually issues. The table below tells you exactly where to get each key from the provider's dashboard and what that key powers inside WaDesk.

Provider | Where to GET the key (provider dashboard) | What it powers in WaDesk
--- | --- | ---
OpenAI | platform.openai.com/api-keys — log in, Create new secret key, copy the `sk-…` value (shown once). | AI chatbot, reply suggestions, content generation (GPT models); Whisper speech-to-text and OpenAI TTS in the voice assistant.
Anthropic | console.anthropic.com/settings/keys — Settings → API keys → Create Key, copy the `sk-ant-…` value. | AI chatbot, reply suggestions, content generation (Claude models).
Google Gemini | aistudio.google.com/app/apikey — Create API key in Google AI Studio. | AI chatbot, reply suggestions, content generation (Gemini models).
Mistral | console.mistral.ai/api-keys — La Plateforme → API Keys → Create new key. | Chat / content generation (Mistral, Codestral, Ministral, Devstral, Magistral).
ElevenLabs | elevenlabs.io/app/settings/api-keys — Profile → API key. (Older UI: avatar menu → Profile + API key.) | Text-to-speech for the voice assistant (high-quality multilingual voices).

### Each Provider's Fields

Every card has one required field — the API key — plus a few optional extras. The extras are only sent to the vendor when you fill them in.

Provider | Required | Optional extras & what to put
--- | --- | ---
OpenAI | API key (the `sk-…` secret) | Organization ID (e.g. `org-xxxxxxxx`), only if you bill to a specific organisation. Get it from platform.openai.com/account/organization.
Anthropic | API key (the `sk-ant-…` secret) | Default max tokens (placeholder `4096`) — a cap on how long each reply can be, not a credential.
Gemini | API key (the AI Studio key) | Project ID, only for Vertex AI billing.
Mistral | API key (the La Plateforme key) | None.
ElevenLabs | API key (the ElevenLabs key) | Default voice ID, used when a caller hasn't picked a voice. Copy it from your Voices library (elevenlabs.io/app/voice-library) → voice → ID.

> Where you paste all of this: the provider's card on this page. The API key goes in the masked API key field; the optional values go in the plain fields beneath it on the same card. Click Save to store them.

## Per-Provider Default Models

Each card has a Default model dropdown. The default model is what WaDesk uses for that provider unless a feature or workspace asks for a different one. The lists are kept in step with each vendor's published models, and retired ones are removed in each update.

Provider | Seeded default | Models offered in the dropdown
--- | --- | ---
OpenAI | `gpt-5.4-mini` | GPT-5.5, 5.5-pro, 5.4, 5.4-pro, 5.4-mini, 5.4-nano, 5-mini, 5-nano; GPT-4.1 and 4.1-mini; then a legacy line with GPT-4o and GPT-4o-mini.
Anthropic | `claude-opus-4-7` | Claude Opus 4.7, Sonnet 4.6, Haiku 4.5 (current flagships); Opus 4.6, Sonnet 4.5, Opus 4.5 (still maintained).
Gemini | `gemini-3.5-flash` | Gemini 3.5 Flash, 3.1 Pro Preview, 3.1 Flash-Lite; plus the maintained 2.5 Pro / Flash / Flash-Lite line.
Mistral | `mistral-large-latest` | large / medium / small "latest" aliases and Codestral-latest; plus dated builds: Ministral 3 (14B / 8B), Devstral 2, Magistral Medium.
ElevenLabs | `eleven_v3` | Eleven v3 (flagship, 70+ languages), Multilingual v2, Turbo v2.5, Flash v2.5.

If a default model was set previously and no longer appears in the curated list, the dropdown keeps it and tags it (custom) so it is never silently dropped.

> Tip: Entries below a legacy marker in a dropdown still work but receive fewer vendor updates. Prefer a current flagship unless a workspace specifically depends on the older model's behavior.

## How to Configure a Provider

1. Open AI / API keys in the admin sidebar.
2. Get the key from the provider's dashboard using the link in the Supported Providers table (for OpenAI, that is platform.openai.com/api-keys).
3. On the matching card in WaDesk, paste the key into the masked API key field.
4. Fill any optional fields the card shows (Organization ID, Project ID, default max tokens, voice ID).
5. Pick a Default model from the dropdown.
6. Click Save. You will see a confirmation such as "OpenAI settings saved."
7. Click the card's Activate button to enable it as a platform fallback.

The stats strip at the top counts your providers: Providers (total), Active (enabled), Ready (active and has a key), and No key set. Use it to confirm at a glance that the providers you rely on are fully set up — you want them showing under Ready.

> Caution — activation guard: A provider cannot be activated until it has a key. If you click Activate on an empty card, the toggle is rejected with "Add an API key before activating." Save the key first, then activate.

## How Keys Are Hidden & Protected

API keys are encrypted when stored, and a saved key is never shown back to you in the page — redisplaying it could leak the secret to browser extensions, screen-share recordings, or screenshots.

The key field therefore works on a "leave blank to keep" basis:

- When a key is already on file, the field shows empty with a placeholder like `•••••••••• (saved — leave blank to keep)`.
- Saving with the key field blank keeps the stored key untouched — so you can change the model or an optional field without re-pasting the secret.
- Typing a new value overwrites the stored key.
- The same "blank keeps it" rule applies to the optional fields, so an empty field never wipes a previously saved value.

> Caution — after a server encryption-key change: Keys are encrypted with your app's master encryption key. If that key is ever changed (a server-level maintenance task), the previously stored API keys can no longer be read. The page handles this gracefully — an unreadable key simply shows as "No key" rather than breaking — but you will need to re-paste every provider key afterwards.

## The Fallback Chain (BYOK → Admin Key)

WaDesk supports two levels of AI keys. When a workspace runs an AI feature, WaDesk picks a key in this order:

1. The workspace's own key (BYOK) — used only when the workspace's plan allows Bring Your Own Key and the workspace has saved its own active key for that exact provider (in its own AI settings). When this is used, the cost falls on the workspace.
2. The matching Active provider on this page — the platform fallback. Used whenever step 1 doesn't apply, i.e. the workspace isn't on a BYOK plan, or is but hasn't set its own key for that provider.
3. Neither — the feature shows a clear error that no key is available.

WaDesk also tracks which source was used, so usage is metered against the correct side. In practice, the providers you mark Active here become the default AI engine for every customer who hasn't brought their own key — their AI features keep working without each customer needing a vendor account.

> Note: Disabling a provider here (deactivating it, or removing its key) immediately stops workspaces without their own key from using that provider. Workspaces that supplied their own key on a BYOK plan are unaffected. Plan an off-hours change if you are switching the platform's primary AI vendor.

## Troubleshooting

Symptom | Likely cause & fix
--- | ---
"Add an API key before activating" | You tried to activate a card with no key on file. Paste the key, click Save, then Activate.
Invalid / unauthorized key (401 from the vendor) | The key was mistyped, revoked, or belongs to a different environment. Re-create it on the provider dashboard (see the links above) and paste the fresh value. For OpenAI also confirm the Organization ID matches the org that owns the key.
Model not available / "model not found" | The selected Default model isn't enabled for your account, or the vendor renamed it. Pick a current flagship from the dropdown. If you previously saved a model that is now tagged (custom), switch it to a listed model.
Quota / rate-limit / billing errors (429 or "insufficient quota") | The vendor account has no billing set up or has hit a usage cap. Add billing / raise limits in the provider dashboard. For OpenAI/Gemini, verify the right Organization / Project is being billed via the optional extra field.
Key worked, now every card shows "No key" | Your server's master encryption key was changed, so the stored keys can no longer be read. Re-paste each provider key (see How Keys Are Hidden & Protected).
A BYOK workspace ignores the admin key | Expected: on a BYOK plan the workspace's own key wins. To force the platform key, remove the workspace key or move it off the BYOK plan (see The Fallback Chain).
No provider cards at all | The starter provider list didn't load. Ask your support team to re-run the install setup to restore the five cards.

## Related Pages

- System Settings — the WhatsApp engine providers (Meta Cloud API, Twilio, Unofficial API) and platform branding.
- Payment Gateways — the same pre-seeded, encrypted, leave-blank-to-keep credential pattern, applied to payments.
- Security & Audit Log — how key changes and other sensitive admin actions are recorded.