Twilio Credentials Security Guide: API Keys, Auth Tokens and Subaccounts

A Twilio Auth Token is a master credential: it authenticates REST API calls, signs every webhook Twilio sends, and through the parent account can reach every subaccount, yet it is often the first credential a developer copies into code. Twilio provides better options, including Standard and Restricted API keys, secondary Auth Tokens for zero-downtime rotation, subaccounts for isolation, short-lived Access Tokens for client SDKs and an event log of credential changes. This guide explains how those credentials relate to each other, which ones belong where, how to rotate them without breaking webhook validation, and what to monitor. It is for platform, application security and identity teams running Twilio messaging, voice or verification workloads, and it describes features from Twilio's documentation without recommending any vendor.

Key takeaways

• The Auth Token does two jobs. It authenticates API calls and is the HMAC key behind the X-Twilio-Signature header, so rotating it affects both outbound calls and inbound webhook validation.
• API keys should carry application traffic. Twilio calls API keys the preferred way to authenticate; Standard keys cannot touch the Accounts or Keys resources, and Restricted keys hold up to 100 specific permissions.
• Main keys and parent credentials are privileged. A Main key equals the Account SID and Auth Token, and parent account credentials can reach the v2010 resources of every subaccount.
• Subaccounts are a blast-radius boundary. Subaccount credentials cannot reach the parent or sibling subaccounts, which makes one subaccount per customer or environment a practical isolation pattern.
• Monitor Events records credential changes. Event types for Auth Token promotion, API key creation and security setting changes give a ready-made detection feed, with 30 days of history on free accounts and 13 months on paid editions.

How identity and access work in Twilio

Twilio separates people from code. People sign in to the Console, optionally through SAML single sign-on managed in a Twilio Organization. Code authenticates to the REST API with HTTP Basic authentication, sending either the Account SID and Auth Token, or an API key SID and secret, as username and password, always over HTTPS. Client-side SDKs (Voice, Video, Conversations, Sync) never hold either: they receive a short-lived Access Token minted by your server. Every one of these programmatic credentials is a non-human identity that needs an owner and a lifecycle. See the Non-Human Identity (NHI) Guide.

Credential types

Regions

For accounts that use Twilio Regions, API credentials are region-specific, so a key created for one region does not authenticate in another, and API keys used for Video Access Tokens must be in the US1 region. Inventories should record the region alongside each key, otherwise rotation scripts will miss keys outside the default region.

Admin roles and privileged access

Privilege in Twilio sits at two levels. At the Organization level, Twilio documents five roles: Owner (one only, full control), Administrator (manages users, accounts and organisation settings, cannot delete the organisation), Standard User (the default, access only to accounts an administrator specifies), Organization Billing Admin and Organization Billing Viewer. Accounts also carry their own account-level roles, which are separate from organisation roles; check the Console for which of those can view the Auth Token and manage keys in your account.

• Keep Owner and Administrator small: these roles control user management, account creation and organisation settings, so they can grant themselves or others credential access. Name the holders and review them quarterly.
• Use Organization SSO: Twilio supports SAML 2.0 SSO, configured by an Organization Administrator in the Admin Center. Logins are service-provider initiated and protected with PKCE, and enforcement applies by verified email domain, after which managed users cannot sign in with a password.
• Provision with SCIM, not just-in-time: Twilio does not support just-in-time provisioning; users must exist before they can sign in, and the SCIM API creates, updates and deactivates them from the identity provider. See the SCIM Provisioning Guide.
• Control domain sign-ups: Organization domain settings decide whether new sign-ups from a verified domain need an invitation, auto-join with account creation rights, or are blocked. Requiring an invitation stops staff creating ungoverned accounts that hold company numbers and credentials.
• Watch external users: users outside the organisation can still be granted access to managed accounts; list them separately and expire their access when a project ends.
• Enforce MFA at the identity provider: with SSO in place, Twilio's documentation leaves mandatory two-factor policy to the identity provider, so set phishing-resistant MFA there.

Integrations, API tokens and service accounts

Choosing the right credential

API keys

Keys are created in the Console under Settings > Account settings > API keys & auth tokens (choosing a region first) or, for Standard and Restricted keys, through the REST API. The secret is displayed at creation and must be copied straight into a vault. Main and Standard keys can only be renamed afterwards; Restricted keys can also have their permissions edited or be duplicated as a template. Deleting a key revokes it, and also revokes every Access Token it signed. Twilio advises issuing separate keys per developer or subsystem so each can be revoked without affecting others.

Subaccounts

• Isolation: each subaccount has its own SID and Auth Token. Subaccount credentials cannot access the parent account or other subaccounts, while parent credentials can reach the v2010 resources of any subaccount.
• Shared fate: usage bills to the parent's single balance, subaccounts use the parent's voice and SMS permissions, and suspending the parent suspends every subaccount.
• Limits and lifecycle: a parent can hold up to 1,000 subaccounts by default. Status can be active, suspended (no calls or SMS, number charges continue) or closed (permanent, numbers released), and closed subaccounts are deleted 30 days after closure by default.
• Decommissioning: when a customer or environment ends, suspend first, rotate or delete its keys, then close. See the NHI Offboarding and Decommissioning Guide.

Access Tokens

Access Tokens are JWTs with header alg HS256 and cty twilio-fpa;v=1, carrying the API key SID as iss, the Account SID as sub, an identity and product grants. The maximum lifetime is 24 hours and Twilio recommends the shortest practical TTL. Because the only revocation lever is deleting the signing key, give token minting its own Standard key so revoking it does not stop server-side API traffic.

Webhooks and the Auth Token

Twilio signs every webhook request with X-Twilio-Signature, an HMAC-SHA1 over the full URL and parameters keyed with the primary Auth Token; JSON bodies add a bodySHA256 parameter. Validate with the SDK helpers rather than custom code, serve endpoints over HTTPS with a publicly trusted certificate (Twilio will not connect to self-signed certificates), and do not rely on IP allowlisting, since Twilio does not publish a fixed range of webhook source addresses. Twilio describes credentials embedded in webhook URLs as a legacy approach. See the Webhook Secrets Security Guide.

Rotating the Auth Token

1. Create a secondary Auth Token in the Console or through the Secondary Auth Token resource. The primary keeps working and keeps signing webhooks.
2. Prepare consumers: load the secondary value into the vault and make API callers ready to use it; webhook validators must keep using the current primary until promotion, because signatures are made with the primary token.
3. Promote: POST https://accounts.twilio.com/v1/AuthTokens/Promote deletes the current primary and makes the secondary primary. Switch webhook validation to the new value at the same moment.
4. Allow propagation: Twilio notes that Services and Functions (Classic) with the token hard-coded need about a minute to pick up the change and return 403 Forbidden otherwise; better still, reference a variable.
5. Bulk rotation: each change emails owners and administrators; the SuppressEmailNotification parameter exists for rotating many subaccounts, but keep notifications on for single, unplanned rotations so a malicious promotion is noticed.

Logging and detection

The Monitor Events API (GET https://monitor.twilio.com/v1/Events) records actions from the API, the Console and Twilio staff, with the actor (actorType of user, account or twilio-admin), source (web, api, twilio), source IP address and changed properties. Free accounts can query 30 days; Administration, Security and Enterprise Edition customers can query 13 months. The list endpoint accepts one field filter per request (for example eventType or sourceIpAddress) plus a date range, so pull everything into a SIEM rather than querying ad hoc.

Pair the event feed with usage data: sudden spikes in outbound SMS or calls to unusual destinations are the typical way stolen messaging credentials are monetised.

Metrics

• Auth Token use in applications: number of services still authenticating with an Auth Token or Main key (target: only named management automations).
• Restricted key coverage: share of single-purpose services on Restricted keys.
• Key age and orphan count: oldest key and keys with no owner or no use in 90 days.
• Auth Token rotation interval per account and subaccount, and time taken in the last drill.
• Unreviewed credential events: credential-related Monitor Events not matched to a change ticket.

Responding to a leaked credential

1. API key leaked: create a replacement, deploy it, then delete the leaked key; remember any Access Tokens it signed die with it.
2. Auth Token leaked: create a secondary token, update consumers and webhook validators, and promote immediately. Then review keys created since the exposure, because an attacker with the Auth Token can create a Main or Standard key that survives rotation.
3. Review Monitor Events and usage for the exposure window, filtering by the source IP addresses and event types above, and check for new subaccounts.
4. Remove the source from repositories, logs and tickets, and rotate again if another copy appears. See the Secrets Rotation Runbook Template.

Hardening baseline

Phased rollout

1. Weeks 1 to 2, inventory: list every account and subaccount, every API key per region and its type, where the Auth Token is used, and scan repositories, CI variables and images for Account SIDs paired with tokens.
2. Weeks 2 to 4, people: set up Organization SSO with domain enforcement, SCIM, invitation-only domain sign-ups and a reviewed list of Owners, Administrators and external users.
3. Weeks 3 to 8, move code off the Auth Token: issue one Restricted key per service in a test account, check for permission errors, promote to production, then remove the Auth Token from the service. Roll back by redeploying the previous secret from the vault while the old credential is still valid.
4. Weeks 6 to 10, rotate the Auth Token once every application has moved, using the secondary token procedure, so any undiscovered copies stop working in a controlled way.
5. Ongoing: stream Monitor Events to the SIEM, rotate on a schedule, and drill a key leak each quarter. Where available on Enterprise or Security Edition, evaluate Public Key Client Validation, which stops the Auth Token being accepted for REST requests (it is not supported for Flex, Studio or TaskRouter).

Small and large organisations

• Small teams: one account, Restricted keys per service, a Standard key for Access Tokens only, the Auth Token kept for management, and environment variables or a vault for storage.
• Larger estates and ISVs: a subaccount per customer or environment, parent credentials confined to a provisioning service, Organization SSO and SCIM, 13-month event retention and Public Key Client Validation where products allow it.

Framework mapping

Relevant MITRE ATT&CK techniques are T1552.001 Credentials In Files for tokens found in code and configuration, and T1098.001 Additional Cloud Credentials for an attacker who creates a new API key to outlast an Auth Token rotation.

Common misconfigurations

• Auth Token in application code: the quickstart pattern of Account SID plus Auth Token survives into production, so a leaked config file exposes the master credential and the webhook signing key at once.
• Rotation that breaks webhooks: validators switched to the new token before promotion, or never switched after it, so legitimate requests fail validation and teams disable the check.
• Parent credentials in tenant services: ISV code uses parent credentials for every customer, removing the isolation subaccounts were meant to provide.
• Main keys mistaken for ordinary keys: a Main key handed to a service has the same reach as the Auth Token, including key management.
• Rotating the token but not the keys: after an exposure, keys created by the attacker remain valid. Review key creation events for the whole exposure window.
• Ignoring provider-side incidents: after the Twilio breach in 2022, Twilio reported no evidence that customer API keys or Auth Tokens were accessed, but a provider incident is still a sound trigger to review scopes and rotate the credentials your systems hold.

Practitioner checklist

• Inventory every account, subaccount, region and API key, with owner and type recorded.
• Move application traffic from the Auth Token to Restricted keys, one per service.
• Dedicate a Standard key to minting Access Tokens and keep token lifetimes as short as practical.
• Confine parent credentials and Main keys to a single, owned management automation.
• Use a subaccount per customer or environment and decommission them with a suspend, revoke, close sequence.
• Rotate the Auth Token through a secondary token and promotion, switching webhook validation at promotion.
• Validate X-Twilio-Signature with SDK helpers on every webhook endpoint over trusted HTTPS.
• Enforce Organization SSO by domain, provision with SCIM and require invitations for new sign-ups.
• Stream Monitor Events to the SIEM and alert on Auth Token, key, account and security setting changes.
• Drill a leaked-credential response each quarter, including a review of keys created during the exposure window.

Standards and references

• Twilio: API keys overview
• Twilio: Auth Token Promotion resource
• Twilio: Subaccounts
• Twilio: Webhooks security
• Twilio: Access Tokens
• Twilio: Monitor Events
• NIST: SP 800-53 Rev. 5
• MITRE ATT&CK: Additional Cloud Credentials

Related NHI Mgmt Group resources: API Key Management Guide · Stripe API Keys Security Guide · SaaS API Token Security Guide · Secrets Management Guide · NHI Authentication Guide