[metadata]
article:modified_time: 2026-08-14T09:01:02.000Z
dcterms.modified: 2026-08-14T09:01:02.000Z
description: Learn about the REST API Auth Token, its properties, and how to promote the secondary Auth Token to primary.
og:updated_time: 2026-08-14T09:01:02.000Z
viewport: width=device-width
x-twilio-docs-origin: otk
x-twilio-docs-source: primary

[canonical-links]
https://www.twilio.com/docs/iam/api/authtoken

[document-links]
/docs
API Keys Overview: /docs/iam/api-keys
Access Tokens: /docs/iam/access-tokens
Account OAuth Apps: /docs/iam/oauth-apps/account-oauth-apps
Account and Key Management with API Keys: /docs/iam/pkcv/account-and-key-management-api-keys
Account: /docs/iam/api/account
All docs...: /docs
Build with AI: /docs/ai
C#/.NET: /docs/iam/connect/quickstart/csharp
Connect your AI agent: /docs/ai/mcp
Conversations: /docs/conversations
Create API Keys in the Console: /docs/iam/api-keys/keys-in-console
Developer Hub: https://www.twilio.com/en-us/developers
Domains: /docs/iam/organizations/domains
Entra ID SCIM integration: /docs/iam/scim/entra-integration
FAQs: /docs/iam/oauth-apps/faqs
Flex: /docs/flex
Functions(Classic): /docs/serverless/functions-assets/functions/migrating-functionsclassic-new-functions-editor
Getting Started: /docs/iam/pkcv/quickstart
HIPAA Accounts: /docs/iam/twilio-editions/hippa
Help Center: https://help.twilio.com
ISO 8601: https://en.wikipedia.org/wiki/ISO_8601
Identity and Access Management (IAM): /docs/iam
Install Twilio Skills: /docs/ai/skills
Java: /docs/iam/connect/quickstart/java
Log in: https://www.twilio.com/login
Managed Accounts: /docs/iam/organizations/managed-accounts
Managed Users: /docs/iam/organizations/managed-users
Messaging: /docs/messaging
Not PII: /docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii
OAuth Token API: /docs/iam/oauth-apps/oauth-access-token
Okta SCIM integration: /docs/iam/scim/okta-integration
Open in ChatGPT: https://chatgpt.com/?hint=search&q=Read%20https%3A%2F%2Fwww.twilio.com%2Fdocs%2Fiam%2Fapi%2Fauthtoken.md%20so%20I%20can%20ask%20questions%20about%20it
Open in Claude: https://claude.ai/new?q=Read%20https%3A%2F%2Fwww.twilio.com%2Fdocs%2Fiam%2Fapi%2Fauthtoken.md%20so%20I%20can%20ask%20questions%20about%20it
Open in Cursor: https://cursor.com/link/prompt?text=Read%20https%3A%2F%2Fwww.twilio.com%2Fdocs%2Fiam%2Fapi%2Fauthtoken.md%20so%20I%20can%20ask%20questions%20about%20it
Open in Perplexity: https://www.perplexity.ai/search?q=Read%20https%3A%2F%2Fwww.twilio.com%2Fdocs%2Fiam%2Fapi%2Fauthtoken.md%20so%20I%20can%20ask%20questions%20about%20it
Organization OAuth Apps: /docs/iam/oauth-apps/org-oauth-apps
Organizations: /docs/iam/organizations
Overview: /docs/iam/access-control/overview
Overview: /docs/iam/api
Overview: /docs/iam/connect
Overview: /docs/iam/oauth-apps/overview
Overview: /docs/iam/pkcv
Overview: /docs/iam/single-sign-on
Overview: /docs/iam/twilio-editions
PHP: /docs/iam/connect/quickstart/php
PII MTL: 0 days: /docs/glossary/what-is-personally-identifiable-information-pii#pii-fields
Privacy Policy: /en-us/legal/privacy
Python: /docs/iam/connect/quickstart/python
RBAC in Legacy Console (Beta): /docs/iam/access-control/rbac-legacy-console
RBAC in Twilio Console: /docs/iam/access-control/rbac-twilio-console
REST API: Accounts Resource: /docs/iam/api/account
REST API: Auth Token: /docs/iam/api/authtoken
REST API: AuthorizedConnectApps Resource: /docs/iam/authorized-connect-apps/api
REST API: ConnectApps Resource: /docs/iam/connect-apps/api
REST API: CredentialAWS Resource: /docs/iam/credentialaws-resource
REST API: CredentialPublicKey Resource: /docs/iam/credentialpublickey-resource
REST API: Credentials: /docs/iam/credentials/api
REST API: Key Resource v1: /docs/iam/api-keys/key-resource-v1
REST API: Key Resource v2010: /docs/iam/api-keys/key-resource-v2010
REST API: Role Assignment Resource: /docs/iam/access-control/role-assignment-resource
REST API: Role Resource: /docs/iam/access-control/role-resource
REST API: Secondary Auth Token: /docs/iam/api/secondary_authtoken
Restricted API Keys: /docs/iam/api-keys/restricted-api-keys
Ruby: /docs/iam/connect/quickstart/ruby
SCIM API overview: /docs/iam/scim
SCIM API reference: /docs/iam/scim/api-reference
SDKs: /docs/libraries
Secondary Auth Token endpoint: /docs/iam/api/secondary_authtoken
Services: /docs/serverless/functions-assets/functions/create-service
Sign up: https://www.twilio.com/try-twilio
Static Proxy for Webhooks: /docs/iam/twilio-editions/twilio-static-proxy
Studio: /docs/studio
Subaccounts: /docs/iam/api/subaccounts
Terms of service: /en-us/legal/tos
Test Credentials: /docs/iam/test-credentials
Twilio Console: https://help.twilio.com/hc/en-us/articles/223136027-Auth-Tokens-and-How-to-Change-Them
Twilio Docs: /docs
Twilio tag: https://stackoverflow.com/questions/tagged/twilio
Types of Roles: /docs/iam/access-control/types-of-roles
Video: /docs/video
View as markdown: /docs/iam/api/authtoken.md
Voice: /docs/voice
support team: https://help.twilio.com

[structured-data]
{"@context":"https://schema.org","@id":"https://www.twilio.com/docs/iam/api/authtoken#article","@type":"TechArticle","author":{"@type":"Organization","name":"Twilio Developer Education Team"},"dateModified":"2026-08-14T09:01:02.000Z","description":"Learn about the REST API Auth Token, its properties, and how to promote the secondary Auth Token to primary.","headline":"REST API: Auth Token","inLanguage":"en","publisher":{"@type":"Organization","name":"Twilio"},"url":"https://www.twilio.com/docs/iam/api/authtoken"}

[content]
REST API: Auth Token | Twilio
Skip to content
Skip to navigation
Skip to topbar
Twilio Docs
Identity and Access Management (IAM)
Getting Started
Overview
Test Credentials
REST API: Auth Token
REST API: Secondary Auth Token
Accounts
REST API: Accounts Resource
Subaccounts
Organizations
Organizations
Managed Accounts
Managed Users
Domains
SCIM API
SCIM API overview
Okta SCIM integration
Entra ID SCIM integration
SCIM API reference
Keys and Tokens
API Keys Overview
Create API Keys in the Console
REST API: Key Resource v1
REST API: Key Resource v2010
Restricted API Keys
Access Tokens
OAuth Apps
Overview
Account OAuth Apps
Organization OAuth Apps
OAuth Token API
FAQs
Credentials
REST API: Credentials
REST API: CredentialPublicKey Resource
REST API: CredentialAWS Resource
Public Key Client Validation
Overview
Getting Started
Account and Key Management with API Keys
Access Control
Overview
RBAC in Twilio Console
RBAC in Legacy Console (Beta)
Types of Roles
REST API: Role Assignment Resource
REST API: Role Resource
Single Sign-On
Overview
Twilio Editions
Overview
HIPAA Accounts
Static Proxy for Webhooks
Twilio Connect
Overview
REST API: ConnectApps Resource
REST API: AuthorizedConnectApps Resource
Quickstarts
C#/.NET
Java
PHP
Python
Ruby
Twilio Docs
Search
Search
Messaging
Voice
Video
Conversations
Flex
Studio
All docs...
Build with AI
SDKs
Help Center
Search
Log in
Sign up
Page tools
Copy as markdown
Useful for sharing or LLM
Copy and view
Copy as markdown
View as markdown
Open in assistant
Open in ChatGPT
Open in Claude
Open in Cursor
Open in Perplexity
Build with AI
Connect your AI agent
Install Twilio Skills
Accelerate development with AI
On this page
Auth Token properties
Update an AuthTokenPromotion resource
Request body parameters
Looking for more inspiration?
Visit the
Developer Hub
On this page
Auth Token properties
Update an AuthTokenPromotion resource
Request body parameters
Copy as markdown
Copy and view
Copy as markdown
View as markdown
Open in assistant
Open in ChatGPT
Open in Claude
Open in Cursor
Open in Perplexity
Build with AI
Connect your AI agent
Install Twilio Skills
REST API: Auth Token
(warning)
Warning
If you are using
Services
or
Functions(Classic)
and have included your auth token directly instead of using a variable, you must wait for 1 minute for the update of your auth token to propagate. Otherwise, those functions and services will fail with a
403 Forbidden
error.
Twilio uses the Account SID and Auth Token to authenticate API requests. You can rotate the Auth Token in the
Twilio Console
or by using this API. Two related endpoints help you manage Auth Tokens: use the
Secondary Auth Token endpoint
to create or delete a secondary token, and use this endpoint to promote the secondary token.
Auth Token properties
Property name
Type
Required
PII
Description
Child properties
accountSid
SID<AC>
Optional
Not PII
The SID of the
Account
that the secondary Auth Token was created for.
Pattern:
^AC[0-9a-fA-F]{32}$
Min length:
34
Max length:
34
authToken
string
Optional
PII MTL: 0 days
The promoted Auth Token that must be used to authenticate future API requests.
dateCreated
string<date-time>
Optional
Not PII
The date and time in UTC when the resource was created specified in
ISO 8601
format.
dateUpdated
string<date-time>
Optional
Not PII
The date and time in GMT when the resource was last updated specified in
ISO 8601
format.
url
string<uri>
Optional
Not PII
The URI for this resource, relative to
https://accounts.twilio.com
Update an AuthTokenPromotion resource
POST https://accounts.twilio.com/v1/AuthTokens/Promote
This action deletes the current primary Auth Token and promotes the secondary Auth Token to primary.
(warning)
Rotating Auth Tokens for many subaccounts
Each Auth Token change sends email to every owner and administrator of the account. Rotating Auth Tokens across many subaccounts at once can generate a high volume of email, which can delay other messages that Twilio sends to the same recipients, such as Console verification codes.
We recommend setting
SuppressEmailNotification
to
true
when you rotate Auth Tokens for a large number of accounts, and telling your users about the rotation through your own channels.
Request body parameters
Encoding type:
application/x-www-form-urlencoded
Schema
Example
Property name
Type
Required
PII
Description
Child properties
suppressEmailNotification
boolean
Optional
Not PII
Whether to suppress the email notification that Twilio sends to the owners and administrators of the account about this Auth Token change. Defaults to
false
, so Twilio sends the email. Set to
true
when rotating Auth Tokens across many subaccounts.
Copy code block
{
"SuppressEmailNotification"
:
true
}
Promote the Secondary Auth Token
.css-1raivgc{box-sizing:border-box;background-color:inherit;color:inherit;font-family:inherit;line-height:1.75rem;padding-top:0.5rem;padding-bottom:0.5rem;padding-left:0.25rem;}
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
Report code block
Copy code block
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const
twilio
=
require
(
"twilio"
);
// Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const
accountSid
=
process.env.
TWILIO_ACCOUNT_SID
;
7
const
authToken
=
process.env.
TWILIO_AUTH_TOKEN
;
8
const
client
=
twilio
(accountSid, authToken);
9
10
async function
updateAuthTokenPromotion
() {
11
const
authTokenPromotion
= await
client.accounts.v1
12
.
authTokenPromotion
()
13
.
update
({ suppressEmailNotification:
false
});
14
15
console.
log
(authTokenPromotion.accountSid);
16
}
17
18
updateAuthTokenPromotion
();
Response
Copy response
1
{
2
"account_sid"
:
"ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
,
3
"auth_token"
:
"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
,
4
"date_created"
:
"2015-07-31T04:00:00Z"
,
5
"date_updated"
:
"2015-07-31T04:00:00Z"
,
6
"url"
:
"https://accounts.twilio.com/v1/AuthTokens/Promote"
7
}
Need some help?
We all do sometimes; code is hard. Get help now from our
support team
, or lean on the wisdom of the crowd by browsing the
Twilio tag
on Stack Overflow.
Terms of service
Privacy Policy
Copyright © 2026 Twilio Inc.
