> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fonoster.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use your own vendor keys

> Run your workspace's calls on your own Deepgram, ElevenLabs, OpenAI, Groq or ai-coustics account, and keep up with model deprecations.

Fonoster calls speech, language and audio vendors for you: a transcriber hears the caller, a voice
speaks, an agent's language model writes the replies, and a noise-cancelling filter cleans the
caller's audio. By default, calls use the platform's account
with each vendor. Set your own key for a vendor, and your workspace's calls use your account
instead: your rate limits, your voices and your contract with the vendor.

The dashboard calls them vendor keys. The API and the CLI call them provider keys
(`SetProviderKey`, `providers:keys:*`).

## Before you begin

* You must be the workspace's owner or an admin to set or remove keys. Members can see which
  vendors have a key.
* Have an API key from the vendor's own console.

## See what you can use

Every provider, model and voice has a **catalog ID** of the form `<provider>/<name>`, such as
`deepgram/nova-3` or `openai/gpt-4o-mini`. Apps and agents name their transcriber, voice and model
by these IDs.

List the catalog your workspace can use:

```bash theme={"system"}
fonoster providers:catalog
```

Narrow it with `--kind` (`provider`, `model` or `voice`) and `--type` (`stt`, `tts` or `llm`):

```bash theme={"system"}
fonoster providers:catalog --kind provider
fonoster providers:catalog --kind model --type stt
```

Each line shows the ID, its kind, type, state and languages:

```text theme={"system"}
ID                      KIND      TYPE  STATE                                   LANGUAGES
deepgram                provider  -     active
elevenlabs              provider  -     active
groq                    provider  -     active
openai                  provider  -     active
```

On Fonoster Cloud the providers are `deepgram` (speech-to-text and voices), `elevenlabs` (voices),
`openai` and `groq` (language models). On your own install, the operator decides. See
[Providers and models](https://docs.fonoster.com/reference/providers.md) for every model and voice.

The catalog only lists providers your workspace can run: those the platform has a key for, plus
those you set your own key for. Setting a key can add a provider to the list.

## Set a key

**Dashboard**

1. Go to **Vendor keys**.
2. Under **Provider**, choose the vendor, such as `deepgram`.
3. Paste your key under **API key**.
4. Choose **Save key**.

The vendor's row now says **Your key** and when you saved it. Rows without one say
**Platform key**.

**SDK**

Set the key with the provider's ID:

```javascript theme={"system"}
const providers = new SDK.Providers(client);

await providers.setProviderKey({
  providerId: "deepgram",
  key: process.env.DEEPGRAM_API_KEY
});
```

See [Workspaces, members and API keys](https://docs.fonoster.com/workspace/access.md#sign-in-from-the-sdk) to create
`client`.

**CLI**

Set the key. Without `--key`, the CLI asks for it and doesn't echo what you type:

```bash theme={"system"}
fonoster providers:keys:set deepgram
```

To set it from an environment variable, pass `--key`:

```bash theme={"system"}
fonoster providers:keys:set elevenlabs --key "$ELEVENLABS_API_KEY"
```

Setting a key again replaces the old one. Fonoster stores it encrypted as a workspace
[secret](https://docs.fonoster.com/workspace/secrets.md) named `provider-key/<provider>`, such as `provider-key/deepgram`. The
dashboard and the CLI never show the key again: they tell you which vendors have a key, not the key
itself.

Calls that start after you save use your key. A change can take up to 30 seconds to reach new
calls. Calls already in progress keep the key they started with.

> [!NOTE]
>
> Fonoster doesn't check the key when you save it. If the vendor rejects it, calls fail at the
> vendor. Make a test call after you set a key.

## Check which keys are set

**Dashboard**

Go to **Vendor keys**. Each provider shows **Your key** or **Platform key**.

**SDK**

```javascript theme={"system"}
const { items } = await providers.listProviderKeys();
// [{ providerId: "deepgram", ref: "...", createdAt: ..., updatedAt: ... }]
```

**CLI**

```bash theme={"system"}
fonoster providers:keys:list
```

```text theme={"system"}
PROVIDER            REF                                     UPDATED
deepgram            5e2a9c1d-7f3b-4a8e-b6d0-1c4f8e2a7b93    2026-10-19T14:02:11Z
```

## Remove a key

Remove your key, and calls go back to the platform's key for that vendor.

**Dashboard**

Go to **Vendor keys**, choose **Remove key** on the provider's row, then **Remove**.

**SDK**

```javascript theme={"system"}
await providers.deleteProviderKey("deepgram");
```

**CLI**

```bash theme={"system"}
fonoster providers:keys:delete deepgram
```

If the platform has no key for that vendor either, the provider drops out of your catalog, and
the **Streams** page warns about each stream that needs a key, with an **Add key** link.

> [!NOTE]
>
> In a private region, calls use only the keys set on the region, not the workspace's vendor keys.
> See [Private regions](https://docs.fonoster.com/private-regions/overview.md).

## If your key can't be read

A call never runs on the platform's key when your own key for a vendor can't be read, for example
when the key store is down or takes longer than 3 seconds. Instead:

* If the app uses that vendor from the start (its voice, its transcriber or its noise-cancelling
  filter), the call is rejected before it's answered, with SIP 503. The `call.failed` webhook and the
  call record give the reason `key_unavailable` and name the vendor.
* If the app asks for that vendor later in the call, for example `speak` with another voice, that
  command gets an `error` with code `key_unavailable`, and the call goes on.
* An agent whose language-model key can't be read says its error message and hangs up.

A workspace with no key for a vendor still uses the platform's key, as before.

## When a model is deprecated

Vendors retire models and voices. When Fonoster deprecates one, it names a replacement and a
retirement date. Until that date nothing changes: your calls keep using the old ID.

You hear about it in three places:

* **Webhook**: a [`provider.deprecated`](https://docs.fonoster.com/reference/webhook-events) event, once per workspace that
  uses the item. Its `data` names the item, the replacement and the retirement date
  (`YYYY-MM-DD`):

  ```json theme={"system"}
  {
    "id": "groq/llama-3.3-70b-versatile",
    "replacement": "groq/openai/gpt-oss-120b",
    "retireOn": "2026-10-15"
  }
  ```

* **Dashboard**: the **Streams** page shows a warning for each deprecated item your apps name or
  used lately, with the retirement date, the replacement and the apps that use it.

* **CLI**: `fonoster providers:catalog` shows the item as `deprecated → <replacement>`.

A call that uses a deprecated item also notes it in its [call record](https://docs.fonoster.com/observe/call-records.md).

### What to do

**1. Switch to the replacement**

Change the transcriber, voice or model in each app and agent that uses the old ID. For an
agent, that's `languageModel.model` or the voice in [its settings](https://docs.fonoster.com/autopilot/build-an-agent.md).

**2. Listen to a test call**

A replacement can sound or behave a little differently. Call the agent with **Talk to agent**,
or call the number, before the retirement date.

### On the retirement date

When Fonoster retires the item, it moves your saved apps and agents to the replacement. Settings
the replacement doesn't accept are dropped. If an app can't move, such as one with a voice that
exists only on the old model, it keeps the old ID, calls use the replacement, and the dashboard
warning stays until you pick a new model or voice yourself.

If a vendor is down, Fonoster doesn't switch your calls to another vendor on its own.

For every command and method, see [Providers in the CLI reference](https://docs.fonoster.com/reference/cli.md#providers) and
[Providers in the Node SDK reference](https://docs.fonoster.com/reference/sdk.md#providers).

## Next steps

> **[Providers and models](https://docs.fonoster.com/reference/providers.md)**
>
> Every model and voice in the catalog, with its languages.

> **[Build an Autopilot agent](https://docs.fonoster.com/autopilot/build-an-agent.md)**
>
> Pick the agent's model, voice and transcriber.

> **[Webhooks](https://docs.fonoster.com/observe/webhooks.md)**
>
> Get `provider.deprecated` and call events on your server.

> **[Secrets](https://docs.fonoster.com/workspace/secrets.md)**
>
> Where your vendor keys are stored.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.