Update a provider API key
You can replace the API key a client uses at any time, without losing their settings or call history. The portal checks the new key with Retell AI, Vapi or ElevenLabs before saving it and shows you exactly which agents and numbers change, so your client’s dashboard keeps working through the switch. Only agency owners and admins can change a key.
Each client is connected to one provider: Retell AI, Vapi or ElevenLabs. The provider cannot be changed after the client is added, but the key can.
- You
Create a new key in the provider
Keep the old key until the switch is done.
- You
Paste it and select Verify Key
In the Connection section of Client settings.
- Voice AI Portal
Compares the two keys
It shows which agents and numbers match, are missing or are new.
- You
Select Update API Key
The new key is saved straight away.
- You
Delete the old key in the provider
Once the client’s dashboard loads with the new key.
Before you begin
Section titled “Before you begin”- You need to be an agency owner or admin. Other team members see Only agency owners or admins can change the API key.
- Use the same provider account. The new key should come from the same account as the old one. A key from another account brings different agents and numbers, and the client loses the ones they had.
Check the connection
Section titled “Check the connection”Each time you open Client settings, the portal checks the client’s saved key with the provider, and a badge in the Connection section shows the result:
| Badge | What it means |
|---|---|
| Checking connection | The check is running. It takes a moment. |
| Connected | The provider accepted the key, and the client’s agents and numbers are loading from it. |
| API key not working | The provider rejected the key, for example because it was deleted or expired. Replace it; see If the old key has already stopped working. |
| Couldn’t check connection | The provider didn’t answer this time. The key is usually fine: select Retry Sync before you change anything. |
The current key is always shown masked, so it stays private on screen.
When to change the key
Section titled “When to change the key”- Routine rotation, as part of your own security policy.
- A key may have leaked. Replace it straight away.
- The key stopped working, for example because it was deleted or expired in the provider. The Connection section of Client settings then shows API Key Invalid; see If the old key has already stopped working.
- Someone with access to the key leaves your team or your client’s team.
Change the key
Section titled “Change the key”-
Create the new key in the provider
Create a replacement key in the client’s provider account, and keep the old key for now. For where to find keys and which permissions to give them, see Connect Retell AI, Connect Vapi or Connect ElevenLabs.
-
Open the client’s settings
Go to Clients and select the settings icon (Client settings) on the client’s row, or open the client and select Client settings in the Agency only box. Connection is the first section on the page.
-
Select Change API Key
Under API key you see the current key, masked. Select Change API Key.
-
Paste the new key and verify it
Paste the new key into New API key, then select Verify Key. The portal checks the key with the provider and shows API key verified successfully, or API key verified with warnings if something needs your attention.
-
Review what changes
A Resource diff preview compares what the new key can see with this client’s current agents and numbers:
Row Meaning Matched Agents and numbers available under both keys. Missing Agents and numbers the new key cannot see. They stop working for this client. New Agents and numbers the new key can see that this client does not use yet. If anything is missing, tick These resources will be lost. I understand and want to continue. If the client has outbound calls in progress, or campaigns that are running or scheduled, you also see how many, and must tick I understand active traffic may be disrupted and want to continue.
-
Select Update API Key
The new key is saved straight away, without waiting for the page’s Save changes bar, and you see API key updated. A second message reminds you to revoke the old key in the provider. If anything was missing under the new key, another message says how many agents or phone numbers “were marked inactive and need reconfiguration”. If outbound calling is on for the client, its outbound campaigns use the new key too.
-
Add any new agents or numbers
If the preview listed new agents or numbers you want this client to use, select them in Agents & numbers, then select Save changes in the bar at the bottom of the page. See Manage workspace assets.
-
Delete the old key in the provider
Once the client’s dashboard is loading data with the new key, delete the old key in the provider account.
If the old key has already stopped working
Section titled “If the old key has already stopped working”When the provider rejects a client’s key, the Connection section shows API Key Invalid.
-
Select Change API Key in the message
The Update API Key dialog opens. To edit other settings first, select Continue with Cached Data instead and come back to the key later.
-
Paste the new key
Paste it into API key and select Validate and Update. If the new key matches the old one’s agents and numbers, it is saved straight away.
-
Confirm any changes
If agents or numbers would be lost, or outbound calls or campaigns are active, the dialog closes and the Resource diff preview opens under API key with the confirmations to tick. Then select Update API Key.
If you see Unable to Connect instead, the key may be fine and the provider temporarily unavailable. Select Retry Sync before you change anything.
What your client notices
Section titled “What your client notices”- Same account, same agents and numbers: nothing changes for your client.
- Agents or numbers missing under the new key: their conversations drop out of the client’s dashboard until you fix the key or select replacements. Tell your client before you go ahead.
- Outbound campaigns: missing agents and numbers are marked inactive for outbound, so a campaign playbook set up with them needs a new agent or number. In Campaign playbooks, select Change setup for this client.
- Client billing on Track and enforce: if the portal has changed the client’s provider settings to stop calls, it restores them with the old key when you update, then applies them again with the new key within about a minute. This is one more reason to keep the old key until the update is done. The new key needs the same access as the old one for this to work; see When a client’s minutes run out.
- Usage keeps being counted: the client’s minutes are read with the new key from the next minute. If the new key can’t read calls, you see Usage can’t be read from the voice provider on the client’s pages after 5 failed reads in a row (your client doesn’t), and minutes aren’t counted until it works.
Troubleshooting
Section titled “Troubleshooting”| Problem | What to do |
|---|---|
| Verification fails straight away | Copy the full key again with no spaces, and check it comes from this client’s provider. For Vapi, use a private key. For Retell AI and ElevenLabs, check the key’s permissions. |
| Too many verify attempts | Each client allows 10 verifications in 10 minutes. Wait a few minutes and try again. |
| Change API Key is not there | Only agency owners and admins can change keys. Ask your agency owner. |
| The error mentions an API key ID | You pasted an ElevenLabs key’s ID instead of the key. Paste the secret key itself, which starts with sk_. |
| “This API key can’t read your agents and phone numbers.” | The key works but lacks permissions. In the provider’s dashboard, give it read access to agents and phone numbers, or create a key without restrictions, then verify again. |
| “Invalid API key” with the provider’s name | The provider doesn’t recognise the key. Copy it again in full, from this client’s provider account. |
| The provider “took too long to answer” | The provider was slow to respond. Try again in a moment. |
| New agents in the provider do not appear | You do not need a new key for that. Select Refresh in Agents & numbers instead. See Manage workspace assets. |
| “agents were marked inactive and need reconfiguration” | The new key can’t see some agents or numbers. Check the key comes from the right account, or select replacements in Agents & numbers and in each campaign playbook set up for this client. |
Can I switch a client to a different provider with a new key?
Section titled “Can I switch a client to a different provider with a new key?”No. The provider is fixed once the client is added. A key from another provider is rejected. To move a client to a new provider, add them as a new client.
Will my client’s call history be lost?
Section titled “Will my client’s call history be lost?”Not if the new key comes from the same provider account. Calls are read from the provider each time the dashboard loads, so the history is still there. A key from a different account shows that account’s calls instead.
How often can I verify a key?
Section titled “How often can I verify a key?”Each client allows 10 verifications in 10 minutes.