Document the ElevenLabs BYOK API key permission requirement

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"

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
 

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 |