Troubleshooting Invalid Access Tokens

Access Tokens are short-lived, JWT-formatted tokens used to authenticate Twilio client-side SDKs, including:

Note: Access Tokens are not the same as Capability Tokens (Twilio Client 1.x, TaskRouter), NTS Tokens (STUN/TURN), or the Auth Token (REST API).

Addressing the Most Common Error Codes

The most common error codes for Access Tokens are due to incorrect account data or timestamp issues:

Authentication Failures and Invalid Tokens

Authentication failures and invalid token errors are usually due to one or more of these components being incorrect or used in the wrong combination:

  • Account SID
  • API Key
  • API Secret

Common Mistakes

  • The Account SID must be from your Live Credentials. Test Credentials are not supported in Access Tokens.
  • Access Tokens are bound to the Account SID specified and cannot be shared across accounts or subaccounts.

Tip: Be sure to use a Twilio Helper Library to generate your tokens and verify you're passing the correct values in the right order for the method signature.

Expired Tokens

Timestamp and expiration issues are usually due to one of the following:

  • TTL is greater than 24 hours
  • Server system clock is skewed
  • Token is not yet valid or already expired

Ensure your server clock hasn't drifted and verify the validity period of the token.

For more insight, inspect your decoded token payload and compare with the details below.

Verify the Access Token Structure

You can decode a token at http://jwt.io/ and verify its structure. The payload section describes the authorization granted. Timestamps are in Unix epoch format.

Example Payload:

{
  "jti": "SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-1450471147",
  "iss": "SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "sub": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "nbf": 1450471147,
  "exp": 1450474747,
  "grants": {
    "identity": "user@example.com",
    "chat": {
      "service_sid": "ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}
Token Property Twilio Implementation Notes

sub

Account SID of the account or subaccount to authenticate
  • Account must be active
  • Must use the Account SID from your Live Credentials
  • Cannot be shared across subaccounts

iss

API Key whose Secret signs the token
  • API Key must be in the account identified by the above Account SID
  • Token must be signed by the Secret matching the API Key

jti

API Key concatenated with a random string
  • Unique identifier for the token
  • Automatically generated by Twilio helper libraries

iat

Timestamp on which the token was issued

nbf

Timestamp when token becomes valid for use

exp

Timestamp on which the token will expire
  • Uses Unix epoch timestamp
  • Ensure server system clock not skewed
  • TTL cannot be greater than 24 hours
  • Token cannot be used after exp

grants

List of permissions granted to the token (varies by product)
  • Must contain at least one grant
  • Multiple grants can be assigned if using multiple Twilio products

All Potential Error Codes

Have more questions? Submit a request
Powered by Zendesk