openai/twilio-iam-auth-setup

Overview

Twilio supports multiple authentication methods. For most developers: use Auth Token for local prototyping, then move to API Keys in production.

| Method | Use for | Security | |--------|---------|----------| | Account SID + Auth Token | Local prototyping, initial testing | Full account access — avoid in production | | Account SID + API Key (Standard) + Secret | All production code | Recommended — revocable, no access to /Accounts or /Keys | | Account SID + API Key (Restricted) + Secret | Fine-grained production access | Best — limit to specific resources only | | Account SID + API Key (Main) + Secret | Account management automation | Full access like Auth Token, but revocable |

For beginners / vibe-coders: Start with Auth Token to get your first API call working, then create a Standard API Key before deploying anything. The key difference: if an API Key leaks, you revoke just that key. If your Auth Token leaks, your entire account is exposed until you rotate it.

---

Prerequisites

• Twilio account — see twilio-account-setup if you don't have one
• Access to the Twilio Console

---

Quickstart

Find your Account SID and Auth Token in the Console dashboard.

Python

import os
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

Node.js

const client = require("twilio")(
    process.env.TWILIO_ACCOUNT_SID,
    process.env.TWILIO_AUTH_TOKEN
);

Never commit Auth Token to version control or use in production.

---

Key Patterns

API Keys (production)

Create: Console > Account > API keys & tokens > Create API key

| Key type | Access | Use case | |----------|--------|----------| | Standard | All resources except /Accounts and /Keys endpoints | Default for production apps | | Restricted | Only the specific resources you grant | Multi-tenant apps, microservices, least-privilege | | Main | Full account access (like Auth Token) | Account management automation (Console-only creation) |

After creation, copy the API Key SID (SK...) and Secret — the secret is shown only once.

Python

client = Client(
    os.environ["TWILIO_API_KEY"],      # SK...
    os.environ["TWILIO_API_SECRET"],
    os.environ["TWILIO_ACCOUNT_SID"]   # required as third argument
)

Node.js

const client = require("twilio")(
    process.env.TWILIO_API_KEY,
    process.env.TWILIO_API_SECRET,
    { accountSid: process.env.TWILIO_ACCOUNT_SID }
);

Restricted API Keys

Restricted keys grant access only to specific Twilio API resources you define. Use them for least-privilege access in production.

Create via the v1 IAM API (not the v2010 /Keys.json endpoint — see CANNOT section):

Python

key = client.iam.v1.api_key.create(
    account_sid=os.environ["TWILIO_ACCOUNT_SID"],
    friendly_name="messaging-only-key",
    key_type="restricted",
    policy={
        "allow": [
            "/2010-04-01/Accounts/{AccountSid}/Messages*"
        ]
    }
)
# Store key.sid and key.secret securely — secret shown only once

Example permission patterns: | Permission | Grants access to | |-----------|-----------------| | /2010-04-01/Accounts/{AccountSid}/Messages* | Send and read messages | | /2010-04-01/Accounts/{AccountSid}/Calls* | Make and manage calls | | /v2/Services/*/Verifications* | Verify API only |

Docs: Restricted API keys

Test Credentials

Make API calls without charges or sending real messages. Find at Console > Account > API keys & tokens > Test credentials.

Python

client = Client(
    os.environ["TWILIO_TEST_ACCOUNT_SID"],
    os.environ["TWILIO_TEST_AUTH_TOKEN"]
)

Node.js

const client = require("twilio")(
    process.env.TWILIO_TEST_ACCOUNT_SID,
    process.env.TWILIO_TEST_AUTH_TOKEN
);

Magic test numbers:

• +15005550006 — valid, can receive messages
• +15005550001 — invalid number (triggers error 21211)
• +15005550007 — number that cannot receive SMS (triggers error 21612)

Auth Token Rotation

Rotate your Auth Token if it's been exposed or as periodic security hygiene. Twilio uses a secondary token promotion model:

1. Console > Account > API keys & tokens > Request a secondary Auth Token
2. Update your application to use the secondary token
3. Once confirmed working, promote the secondary to primary
4. The old primary token is immediately invalidated

Python

# Promote secondary Auth Token to primary via API
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])
account = client.api.accounts(os.environ["TWILIO_ACCOUNT_SID"]).update(
    auth_token_promotion="promote"
)

Important: Auth Token rotation invalidates all active sessions using that token. Plan the switchover to minimize downtime.

API Keys cannot be rotated — if an API Key is compromised, delete it and create a new one:

• Console > Account > API keys & tokens > select key > Delete
• Or via API: client.keys(key_sid).delete()

Docs: Auth Token REST API

Access Tokens (client-side SDKs)

Short-lived JWTs for authenticating browser/mobile clients (Voice JS SDK, Conversations SDK, Video SDK). Generate server-side and pass to the client.

Python

from twilio.jwt.access_token import AccessToken
from twilio.jwt.access_token.grants import VoiceGrant

token = AccessToken(
    os.environ["TWILIO_ACCOUNT_SID"],
    os.environ["TWILIO_API_KEY"],
    os.environ["TWILIO_API_SECRET"],
    identity="user-123",
    ttl=3600
)
token.add_grant(VoiceGrant(outgoing_application_sid="APxxxx"))
print(token.to_jwt())

Node.js

const { AccessToken } = require("twilio").jwt;
const { VoiceGrant } = AccessToken;

const token = new AccessToken(
    process.env.TWILIO_ACCOUNT_SID,
    process.env.TWILIO_API_KEY,
    process.env.TWILIO_API_SECRET,
    { identity: "user-123", ttl: 3600 }
);
token.addGrant(new VoiceGrant({ outgoingApplicationSid: "APxxxx" }));
console.log(token.toJwt());

Available grant types: VoiceGrant, VideoGrant, ChatGrant (Conversations), SyncGrant

Environment Variable Reference

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Option 1: Auth Token (testing only)
TWILIO_AUTH_TOKEN=your_auth_token

# Option 2: API Key (production)
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_SECRET=your_api_secret

# Test credentials
TWILIO_TEST_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_TEST_AUTH_TOKEN=your_test_auth_token

---

CANNOT

• Standard keys cannot access /Accounts or /Keys endpoints — Returns error 20003 (401). Must use Auth Token or Main API Key for account management.
• No restricted key creation via v2010 API — The v2010 /Keys.json endpoint silently ignores KeyType=restricted and Policy parameters, creating a standard key instead. Use the v1 IAM API.
• Restricted keys cannot generate Access Tokens — Only Standard and Main keys can create client SDK tokens.
• No individual Access Token revocation — Tokens are valid until expiration (max 24h). To revoke early, delete the API key that issued them.
• Subaccount credentials cannot access parent or sibling resources — Each subaccount has its own Auth Token and API Keys. Use the subaccount's own credentials to access its resources — never the parent account's credentials.
• API Keys cannot be rotated — No key rotation API exists. To replace a compromised key: create a new key, update your app, then delete the old key.
• PKCV is an advanced feature for compliance-heavy industries — Public Key Client Validation adds client-certificate-style auth. Incompatible with Flex, Studio, and TaskRouter. Once enforcement is enabled, Auth Token authentication is disabled (one-way door). See PKCV docs — consider this only if your security team requires mutual TLS-equivalent authentication.
• Test credentials work with only 4 endpoints — Messages, Calls, IncomingPhoneNumbers, and Lookups. All other endpoints return 403.
• API Key Secret shown only at creation — Cannot be retrieved afterward. If lost, create a new key.
• FriendlyName max 64 characters for keys — 65+ characters returns error 70001.
• Restricted keys limited to 100 permissions per key — Exceeding this limit is rejected at creation.
• Cannot create Main API Keys via REST API — Console only
• Cannot set Access Token TTL beyond 24 hours — Maximum lifetime is 24h
• Cannot use test credentials with real numbers — Test credentials only work with test magic numbers

---

Next Steps

• Account setup and phone numbers: twilio-account-setup
• Security best practices (credential management, key rotation): twilio-security-hardening
• Restricted API keys (fine-grained permissions): Docs
• Auth Token rotation: REST API