Skip to main content

Access Tokens

Additional Developer Resources

To use any of Mapbox's tools, APIs, or SDKs, you'll need a Mapbox access token. You learn the basics about access tokens, such as creating new tokens or deleting existing ones by following the Getting Started Token Guide. This guide covers more advanced topics, like scopes, token rotation, etc.

There are two main types of tokens:

  • Public Tokens - for use in client-side applications
  • Secrets Tokens - for use in server-side applications

Public Tokens​

Public tokens are designed to be used in client-side applications, meaning they can be safely exposed in web browsers, mobile apps, and other client environments.

They typically have limited permissions to access resources like tilesets, styles, datasets, and geocoding services. Public tokens restrict users from changing, deleting, or creating resources, granting only read access.

These tokens are ideal for applications where you expect end users to interact with Mapbox maps (e.g., displaying a map in a mobile or web app) without needing administrative privileges.

Since they are exposed in the client, they are considered less secure than private tokens. They should be configured with the least amount of access necessary to limit exposure.

Your Default public token​

A default public token is automatically added to your Mapbox account so you can get started quickly without having to create a token yourself. It is intended for use in development, and should be replaced with a new public token once your app is ready for deployment.

This default public token is located at the bottom of your accounts page. If you would like to create additional public token for established projects, see our Creating additional public access tokens below.

Secret Tokens​

Secret tokens are designed for server-side applications, keeping them hidden from end users.

These tokens often have broader permissions, allowing full access to Mapbox resources, including creating, modifying, and deleting resources such as tilesets, styles, datasets, etc.

Since they provide elevated access, private tokens should never be exposed in client-side code. They are intended for environments where their confidentiality can be guaranteed, such as on a server or in an API.

Creating and deleting access tokens​

You can create and delete access tokens in your account dashboard at account.mapbox.com. Follow the sections below to learn how to create and delete tokens.

Creating public tokens​

To create a new public token, follow these steps:

  1. Go to your account page.
  2. Click the Create a token button.
  3. Name your token something relevant to the project it will be used in.
  4. Next scroll to the scope section and select the only the scopes the public token should have access to. To learn more about scopes, see the Scopes section.
  5. Click the Create token button at the bottom of the page to create your token.
  6. Enter your password to confirm the creation of your token.

Now, you'll be returned to your account's tokens page, where you can copy your new token.

This video walks through the steps above:

Public Token Patterns

All secret access tokens start with pk.

Creating secret tokens​

To create a new secret token, follow these steps:

  1. Go to your account page.
  2. Click the Create a token button.
  3. Name your token something relevant to your token's needs.
  4. Scroll down to the Secret Scopes section and check the relevant scope boxes.
  • This will be specified in whatever tutorial or guide you are following along with, so be sure to only allow the necessary scopes required.
  • To learn more about scopes, see the Scopes section above.
  1. Scroll down and click the Create token button at the bottom of the page to create your token.
  2. Enter your password to confirm the creation of your token.

Now, you'll be returned to your account's tokens page, where you can copy your created token.

Storing Secret Tokens

This token is a secret token, which means you will only have one opportunity to copy it, so save this token somewhere secure.

The following video walks through an example of creating a token with the Downloads:Read scope, so the developer can add the Mapbox Maps Android SDK to their project.

Secret Token Patterns

All secret access tokens start with sk.

Deleting tokens​

If you would like to delete a token, follow these steps:

  1. Go to your account's Access Token page. You may be prompted to log into your account.
  2. Find the token you would like to delete in your list of tokens.
  3. Click the 3 dots next to the token and select delete in the dropdown.
  4. Review the information presented on the prompted confirmation screen and confirm the data shown is what you would expect for usage on this token.
  5. Once your review is finished, click the blue Yes, delete token button.
  6. Enter your password and click the submit button to delete your token.

You will see a small green prompt at the top of the screen confirming your token has been deleted and the token will no longer appear in your token list.

Tokens API​

The Mapbox Tokens API let's you create and delete tokens programmatically. This can be useful for rotating tokens or managing large numbers of tokens associated with a single account.

To learn how to create tokens with the Token API see the Create a Token section of the Token API guide.

To learn more about deleting tokens programmatically, see our the delete a token section of our Token API.

Refreshing Your Default Public token​

Your account always has a default public access token. It can be refreshed, but cannot be deleted.

Follow these steps to refresh your default public access token:

  1. Go to your account's Access Token page. You may be prompted to log into your account.
  2. Find your Default public token which should be at the top of your list of tokens.
  3. Click the refresh button.
  4. Review the information presented on the confirmation prompt and confirm the data shown is what you would expect.
  5. Once your review is finished, click the blue Yes, refresh token button.
  6. Enter your password and click the submit button to delete your token.

Now you have a new default public access token. Note that all references to your previous token will no longer work and will need to be replaced with the new token value.

Scopes​

Each access token you create will have a set of permissions that allow the token to make certain types of requests to Mapbox APIs -- these are called scopes. The API documentation lists the scopes required for each Mapbox API. When creating an access token, you will have the option to add public or secret scopes to the token.

For a complete list of available scopes and recommendations see the Account documentation.

Security for Scopes and Tokens

We recommend only selecting the scopes necessary for the intended use of the token.

URL restrictions​

You can make access tokens for web maps more secure by adding URL restrictions. When you add a URL restriction to a token, that token will only work for requests that originate from the URLs you specify. Tokens without restrictions will work for requests originating from any URL.

For more information on requirements and details for implementing URL restrictions, see the Account documentation.

Token use statistics​

You can see the use statistics for all your tokens, for any specified period, on your Mapbox account Statistics page.

How do access tokens work?​

Mapbox uses JSON Web Tokens (JWT) as the token format. Each token is a string delimited by dots into three parts: header, payload, and signature as described in the Tokens API documentation. Every token has a metadata object that contains properties with information about the token, like id (unique identifier), note (human readable name), scopes (capabilities), allowedURLs (URLs that token is authorized for), and timestamps for created and modified (last modification). For more information on the metadata object’s properties, see our Tokens API documentation

Additional Resources​

Additional Developer Resources
Was this page helpful?