Overview
Twilio supports Regional Auth Tokens to enhance security and compliance for customers operating in multiple geographic regions. These tokens are visible in the Twilio Console under API Keys & Tokens when you select a specific region (e.g., United States (US1), Australia, Ireland, etc.). However, many users wonder if these tokens can be accessed or managed programmatically via the Twilio REST API.
This article clarifies the current capabilities and best practices for handling Regional Auth Tokens, especially in multi-region and subaccount scenarios.
Environment
legacy Twilio Console
What You Need To Know
1. Retrieving Regional Auth Tokens via API
-
No Direct API Access:
Twilio does not provide an API endpoint to programmatically retrieve Regional Auth Tokens for your account or subaccounts. -
Console-Only Access:
Auth Tokens for each region are only accessible via the Twilio Console. For security reasons, they are not exposed through the REST API or any other programmatic method.
2. Managing Regional Auth Tokens for Subaccounts
-
Subaccount Creation:
When you create a subaccount (via API or Console), it will have its own set of Auth Tokens for each supported region. -
Manual Retrieval Required:
These tokens must also be accessed manually through the Console by switching to the desired region and subaccount. -
No Bulk API Retrieval:
There is no API to generate or fetch all regional tokens for an account or subaccount in bulk.
3. Workaround for Subaccount Regional Auth Token Retrieval
-
Subaccounts API Behavior:
After creating a subaccount, you can use the Subaccounts API to fetch the subaccount details. -
Regional Credentials Required:
To retrieve the regional Auth Token, you must authenticate the API request using the parent account’s regional credentials (i.e., the Auth Token for the specific region).Example Request:
curl -X GET -u [main_account_sid]:[main_account_!regional!_token] \ https://api.dublin.ie1.twilio.com/2010-04-01/Accounts/[subaccount_sid].json
Replace[main_account_sid],[main_account_!regional!_token], and[subaccount_sid]with your actual values.
4. Recommended Approach for Multi-Region Authentication
-
Manual Secure Storage:
For secure, multi-region authentication, manually retrieve and securely store the Auth Tokens for each region you intend to use. -
Use Regional Endpoints:
When making API requests to a specific region, use the corresponding regional endpoint and the Auth Token for that region.
Frequently Asked Questions
Can I retrieve all my regional Auth Tokens via a single API call?
No, for security reasons, Twilio does not expose Auth Tokens via API. They must be accessed manually in the Console.
Is there a way to automate regional Auth Token management?
At this time, automation is not supported. Manual retrieval and secure storage are required.
What if I cannot access the Subaccounts API documentation?
If the direct link is unavailable, search for "REST API: Subaccounts" in the Twilio API documentation.
Conclusion
- Regional Auth Tokens are only accessible via the Twilio Console.
- There is no API to retrieve these tokens programmatically for security reasons.
- For subaccounts, you can use the Subaccounts API with regional credentials as a workaround, but the process still requires manual steps.
- Always use the correct regional endpoint and Auth Token for API requests in a multi-region setup.
Below you will find references to useful documents:
If you have further questions or need clarification, please refer to the resources above or reach out for additional guidance.