Document Twilio phone number import with restricted API key

fern/phone-numbers/import-twilio.mdx

@@ -1,12 +1,12 @@
 ---
 title: Import number from Twilio
-subtitle: Import a new or existing number from Twilio
+subtitle: Import a new or existing number from Twilio using API Keys
 slug: phone-numbers/import-twilio
 ---
 
 ## Overview
 
-As you scale your agents, you may want to use other telephony providers, like Twilio. In this guide, you'll learn how to add a new or existing Twilio number to Vapi.
+As you scale your agents, you may want to use other telephony providers, like Twilio. In this guide, you'll learn how to add a new or existing Twilio number to Vapi using a Twilio API Key (recommended) instead of an Auth Token. Restricted API Keys are supported and preferred for least‑privilege access.
 
 ## Prerequisites
 
@@ -15,35 +15,76 @@ As you scale your agents, you may want to use other telephony providers, like Tw
 ## Get started
 
 <Steps>
-  <Step title="Buy a Phone Number via Twilio (if needed)">
+  <Step title="Buy a phone number in Twilio (if needed)">
     If you don't have a Twilio number, purchase one in your Twilio console's "Buy a number" section.
     <Frame caption="The Twilio 'Buy a Number' page in the Twilio console.">
       <img src="../static/images/quickstart/phone/buy-phone-number-twilio.png" />
     </Frame>
   </Step>
-  <Step title="Get Your Twilio Account SID & Auth Token">
-    In your Twilio console, go to "API keys & tokens" to find your Account SID and Auth Token.
-    <Frame caption="Navigate to the credentials section of your Twilio account.">
+  <Step title="Create a Twilio API Key (Restricted or Standard)">
+    Use a Restricted API Key for least‑privilege access. You'll provide this key to Vapi when importing your number.
+    <Info>Restricted keys are available to all Twilio users—no access request needed.</Info>
+
+    1. In the Twilio console, open <b>API keys & tokens</b> and click <b>Create new API key</b>.
+    <Frame caption="Navigate to the API Keys & Tokens section in Twilio.">
       <img src="../static/images/quickstart/phone/twilio-api-key-nav.png" />
     </Frame>
-    <Frame>
+    <Frame caption="Find your Account SID under Account Info (you'll need this).">
       <img src="../static/images/quickstart/phone/twilio-credentials.png" />
     </Frame>
+    2. Give the key a friendly name and choose <b>Restricted (Beta)</b> as the type.
+    3. Grant the following permissions:
+
+    - <b>Voice → Calls</b>: Read, List, Create, Update, Delete
+    - <b>Voice → Conferences</b>: Read, List, Create, Update, Delete
+    - <b>Phone Numbers → Active Numbers</b>: Read, List, Create, Update, Delete
+
+    <Frame caption="Restricted Key permissions — Voice: Calls & Conferences (all CRUD).">
+      <img src="../static/images/quickstart/phone/twilio-restricted-permissions-voice.png" />
+    </Frame>
+    <Frame caption="Restricted Key permissions — Phone Numbers: Active Numbers (all CRUD).">
+      <img src="../static/images/quickstart/phone/twilio-restricted-permissions-phone-numbers.png" />
+    </Frame>
+
+    4. Click <b>Create</b>, then securely copy the <b>API Key SID</b> and <b>Secret</b>.
+    <Warning>The Secret is shown only once. Store it in a secure location.</Warning>
+    <Frame caption="Restricted API Key created — copy the SID and Secret securely.">
+      <img src="../static/images/quickstart/phone/twilio-restricted-key-created.png" />
+    </Frame>
   </Step>
-  <Step title="Import Your Number in the Vapi Dashboard">
-    1. Go to the "Phone Numbers" section in Vapi and click "Import".
+  <Step title="Import your number in the Vapi Dashboard">
+    1. Go to the <b>Phone numbers</b> section in Vapi and click <b>Import</b>.
     <Frame caption="Click 'Import' in the 'Phone Numbers' tab of your dashboard.">
       <img src="../static/images/quickstart/phone/dashboard-import-phone-number.png" />
     </Frame>
-    2. Enter your phone number and Twilio credentials, then click "Import".
+    2. Enter your phone number, Twilio <b>Account SID</b>, <b>API Key SID</b>, and <b>API Secret</b>, then click <b>Import</b>.
     <Frame>
       <img src="../static/images/quickstart/phone/import-twilio-number-dashboard.png" />
     </Frame>
   </Step>
-  <Step title="Your number is ready now ready">
-    You can use the number with an assistant for inbound or outbound calls. 
+  <Step title="Import via API (optional)">
+    Use the API to import your Twilio number programmatically using your API Key SID/Secret.
+
+```bash title="Import Twilio number with API Key"
+curl -X POST https://api.vapi.ai/phone-number \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "provider": "twilio",
+    "number": "+15551234567",
+    "twilioAccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    "smsEnabled": false,
+    "twilioApiKey": "SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    "twilioApiSecret": "<YOUR_TWILIO_API_SECRET>"
+  }'
+```
+  </Step>
+  <Step title="Your number is ready">
+    You can now use the number with an assistant for inbound or outbound calls.
     <Frame caption="The phone number detail page, where you can configure your phone number.">
       <img src="../static/images/quickstart/phone/phone-number-import-complete.png" />
     </Frame>
   </Step>
-</Steps> 
+</Steps>
+
+<Tip>If you previously imported numbers using an Auth Token, you can continue doing so. However, using a Restricted API Key is recommended for better security and tighter scope.</Tip>