From b3ed0856ba37816dbbec2aea7c6322847ac1d174 Mon Sep 17 00:00:00 2001
From: Chiranjeet Mishra <chiranjeet@vapi.ai>
Date: Mon, 7 Sep 2026 06:35:21 +0000
Subject: [PATCH] Document the ElevenLabs BYOK API key permission requirement

An ElevenLabs API key with endpoint access restrictions is accepted in
Integrations but fails when Vapi calls a restricted endpoint. ElevenLabs
returns "The API key you used is missing the permission voices_read to
execute this operation." on voice search, and rejects voice library sync
outright, so the voice looks missing and the library never syncs.

Nothing on the ElevenLabs or Integrations pages stated that the key needs
unrestricted endpoint access, so the requirement was only discoverable
from the failure.

- custom-voices/elevenlabs: state the requirement on the step where the
  key is created, and add troubleshooting for the two failure symptoms
- providers/voice/elevenlabs: note the requirement where BYOK is offered
- providers/integrations: note that a provider key needs access to every
  endpoint Vapi calls
---
 .../custom-voices/elevenlabs.mdx              | 23 +++++++++++++++++++
 fern/providers/integrations.mdx               |  6 ++++-
 fern/providers/voice/elevenlabs.mdx           |  4 ++++
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/fern/customization/custom-voices/elevenlabs.mdx b/fern/customization/custom-voices/elevenlabs.mdx
index 664e5e994..181fdd651 100644
--- a/fern/customization/custom-voices/elevenlabs.mdx
+++ b/fern/customization/custom-voices/elevenlabs.mdx
@@ -14,6 +14,12 @@ This guide outlines the procedure for integrating your cloned voice with ElevenL
   </Step>
   <Step title="Retrieve your API key">
     Go to the 'Profile + Keys' section on the ElevenLabs website to get your API key.
+
+    <Warning>
+      Create the key without endpoint access restrictions. ElevenLabs lets you [limit which endpoints a key can access](https://elevenlabs.io/docs/api-reference/authentication), and Vapi needs a key that can reach both the text-to-speech endpoints, to generate speech during calls, and the voices endpoints, to list, search, and sync your voices into Vapi. A key that cannot reach one of them fails when Vapi calls that endpoint, which shows up as a missing voice or a library that will not sync.
+
+      If you need to cap what the key can spend, use ElevenLabs' credit quota on the key instead of endpoint restrictions.
+    </Warning>
   </Step>
   <Step title="Enter your API key in Vapi">
     Navigate to the [Vapi Integrations section](https://dashboard.vapi.ai/settings/integrations) and input your ElevenLabs API key under the ElevenLabs section.
@@ -25,6 +31,23 @@ This guide outlines the procedure for integrating your cloned voice with ElevenL
   </Step>
 </Steps>
 
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Your cloned voice does not appear when you search for it">
+    Searching for a voice reads the voice list from your ElevenLabs account with your key. If the key cannot read voices, Vapi gets nothing back and the voice does not appear in search results, even though it still exists in ElevenLabs. ElevenLabs rejects the request with:
+
+    ```
+    The API key you used is missing the permission voices_read to execute this operation.
+    ```
+
+    Generate a key without endpoint access restrictions, then save it again in [Integrations](https://dashboard.vapi.ai/settings/integrations).
+  </Accordion>
+  <Accordion title="Your voice library does not sync, or newly added voices never appear">
+    Syncing the library calls your ElevenLabs account with your key. If ElevenLabs rejects the request, the sync fails and no voices are added. Confirm the key still exists in your ElevenLabs account, has not been rotated, and has no endpoint access restrictions.
+  </Accordion>
+</AccordionGroup>
+
 **Video Tutorial:**
 <iframe
   src="https://www.loom.com/embed/91568c17289740889c278f458f0d291c?sid=a0c812fa-5809-4ffa-8391-6a578c3e0608"
diff --git a/fern/providers/integrations.mdx b/fern/providers/integrations.mdx
index 463c8160b..07f98b788 100644
--- a/fern/providers/integrations.mdx
+++ b/fern/providers/integrations.mdx
@@ -16,7 +16,11 @@ When you add your own credentials for a provider, Vapi uses your account with th
 ## Prerequisites
 
 * An account with the provider you want to connect.
-* That provider's API key or credentials.
+* That provider's API key or credentials, with access to every endpoint Vapi calls for that provider.
+
+<Note>
+  Some providers let you restrict an API key to a subset of their API. Vapi needs a key that can reach every endpoint it uses for that provider, so check the provider's page under [Voices](/providers/voice/overview), [Models](/providers/model/overview), or [Transcribers](/providers/transcriber/overview) for any key requirements before you create the key.
+</Note>
 
 ## Steps
 
diff --git a/fern/providers/voice/elevenlabs.mdx b/fern/providers/voice/elevenlabs.mdx
index eed3dc22d..548d988d0 100644
--- a/fern/providers/voice/elevenlabs.mdx
+++ b/fern/providers/voice/elevenlabs.mdx
@@ -9,6 +9,10 @@ ElevenLabs provides text-to-speech for Vapi voice agents.
 
 You can use ElevenLabs through Vapi's default integration, or connect your own account in [Integrations](/providers/integrations).
 
+<Note>
+  If you connect your own ElevenLabs account, the API key must not have endpoint access restrictions. See [set up a custom ElevenLabs voice](/customization/custom-voices/elevenlabs) for the requirement and the symptoms of a restricted key.
+</Note>
+
 ## Supported capability
 
 | Capability | Provider value |