Use your own vendor keys

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:

fonoster providers:catalog

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

fonoster providers:catalog --kind provider
fonoster providers:catalog --kind model --type stt

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

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 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
SDK
CLI

Go to Vendor keys.
Under Provider, choose the vendor, such as deepgram.
Paste your key under API key.
Choose Save key.

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

Set the key with the provider’s ID:

const providers = new SDK.Providers(client);

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

See Workspaces, members and API keys to create client.

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

fonoster providers:keys:set deepgram

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

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 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.

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
SDK
CLI

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

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

fonoster providers:keys:list

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
SDK
CLI

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

await providers.deleteProviderKey("deepgram");

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.

In a private region, calls use only the keys set on the region, not the workspace’s vendor keys. See Private regions.

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 event, once per workspace that uses the item. Its data names the item, the replacement and the retirement date (YYYY-MM-DD):
{ "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.

What to do

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.

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 and Providers in the Node SDK reference.

Next steps

Providers and models

Every model and voice in the catalog, with its languages.

Build an Autopilot agent

Pick the agent’s model, voice and transcriber.

Webhooks

Get provider.deprecated and call events on your server.

Secrets

Where your vendor keys are stored.

Get started

Autopilot

Streams

Telephony

Observe

Workspace

Reference

Self-hosting

Private regions

Hacking Fonoster

Use your own vendor keys

Before you begin

See what you can use

Set a key

Check which keys are set

Remove a key

If your key can’t be read

When a model is deprecated

What to do

On the retirement date

Next steps

Providers and models

Build an Autopilot agent

Webhooks

Secrets

​Before you begin

​See what you can use

​Set a key

​Check which keys are set

​Remove a key

​If your key can’t be read

​When a model is deprecated

​What to do

​On the retirement date

​Next steps

Providers and models

Build an Autopilot agent

Webhooks

Secrets

Before you begin

See what you can use

Set a key

Check which keys are set

Remove a key

If your key can’t be read

When a model is deprecated

What to do

On the retirement date

Next steps