Troubleshooting Access Tokens
This troubleshooting page will walk you through the common mistakes when making tokens and common token errors.
If you are using the Tokens API instead of managing tokens from your account page, view the Token API Errors table instead.
Why can't I edit my secret token?
Mapbox does not allow editing of secret tokens for security reasons. You will need to create a new secret token instead.
Should I use a public or secret token?
For most use cases where you are reading resources from Mapbox (such as loading a map or performing location searches), you will use a public token. Secret tokens are usually required for uses that require writing data, such as creating Mapbox Tiling Services recipes, uploading data, or writing a style. Consult the documentation for the product(s) you are using to determine which type of access token is required.
To learn more about the difference between public and private tokens, view the What is the difference between a public token and a secret token? FAQ
Token Errors
401 (Unauthorized)
If your token is deleted or if you've refreshed your default public token and are using an old token, you may receive an error status of 401.
Make sure you are using a token that is still active. You can check which tokens are active by going to your account's access token list in your account.
403 (Forbidden)
Potential Cause 1: Missing Scopes
If your token is missing a required scope, the token will return a 403 status code. For example, if you are trying to load the style of a map, make sure you have the STYLES:READ scope selected.
For public tokens you can adjust the selected scopes by going to the access token list in your mapbox account and clicking the 3 dots next to the broken token in question and click Edit. This will bring up the edit menu where you can scroll down and adjust the scopes of the token. We recommend for public tokens having all scopes selected.
For private tokens, you can't change the scopes after creation and we recommend creating a new secret token. Make sure to follow any relevant tutorials to know which scopes to select when creating your new token.
Potential Cause 2: URL restrictions
If your token contains a URL restriction and a request is called from an unauthorized URL, the token will return the 403 status code. Make sure the URL your token is being called from is within the URL restrictions set on the token.
Other Helpful Links
Learn more about token basics and getting started creating tokens.
Learn more about advanced token topics.