How Mapbox works

Access tokens

To use any of Mapbox's tools, APIs, or SDKs, you'll need a Mapbox access token. Mapbox uses access tokens to associate API requests with your account. You can find your access tokens, create new ones, or delete existing ones on your Access Tokens page or programmatically using the Mapbox Tokens API.

How access tokens work

Scopes

Each access token you create will have a set of permissions that allow you to make certain types of requests to Mapbox APIs -- these are called scopes. Some Mapbox APIs only accept requests that include tokens with a particular scope. When creating an access token, you will have the option to add additional public or private scopes to your token. If you choose to add any secret scopes to your token, you will have only one chance to view the token.

When choosing scopes, consider what you plan to do with the token. To protect your account and your data, do not grant more scopes than necessary to each token. For example, if you are creating a token to upload data to Mapbox with the Mapbox Uploads API, you will want to make sure you select the uploads:write and uploads:read scopes. To display a map in a web or mobile application, you should create a separate access token that does not include the private uploads-related scopes, but does include the public styles:read and fonts:read scopes.

Our API documentation lists the scopes required for each Mapbox API.

Access token scopes

Public scopes:

ScopeDescription
styles:tilesRead style as PNG tiles and static images. This is the scope that is necessary for retreiving a static map from a style with the Static API.
styles:readRead styles. This is the scope that is necessary to initialize a Mapbox map style in Mapbox GL JS and our mobile Maps SDKs.
fonts:readRead fonts. This is the scope that is necessary to generate fonts that render on your map styles and to retreive font glyphs and ranges using the Mapbox Fonts API.
datasets:readRead datasets. This scope is necessary for retreiving information about datasets using the Datasets API.

Secret scopes:

ScopeDescription
scopes:listList all available scopes. This scope is necessary to list all potential scopes that you have access to based on your plan level using the Tokens API.
map:readRead tilesets, tilestats, legacy Mapbox Studio Classic styles, and legacy projects.
map:writeCreate and update legacy Mapbox Studio Classic styles, tilesets, and tilestats.
user:readRead user profile information. Use this scope to list details about your account.
user:writeWrite user profile information. Use this scope to update your account information.
uploads:readRead data uploads. This scope is necessary for tracking your upload statuses using the Mapbox Uploads API.
uploads:listList tileset uploads. This scope is necessary for retreiving multiple upload statuses using the Mapbox Uploads API.
uploads:writeCreate tileset uploads. This scope is necessary for creating an upload using the Mapbox Uploads API.
styles:writeCreate and update styles. This scope is necessary for creating a style in your account using the Mapbox Styles API.
styles:listList styles. This scope is necessary for listing styles for a specific account using the Mapbox Styles API. This endpoint returns style metadata instead of returning full styles.
tokens:readRead tokens. This scope is necessary to list all the tokens that belong to an account using the Mapbox Tokens API.
tokens:writeCreate, update, and delete tokens using the Mapbox Tokens API. Every requested scope must be present in the access token used to allow the request. It is not possible to create a token with access to more scopes than the token that created it.
datasets:listList datasets. This scope is necessary to list all the datasets that belong to a particular account using the Datasets API.
datasets:writeCreate and update datasets using the Datasets API.
tilesets:listList tilesets. This scope is necessary to list raster and vector tilesets that belong to a particular account using the Mapbox Tilesets API.
tilesets:readRead tilesets. This scope is necessary to read raster and vector tileset information using the Mapbox Tilesets API.
tilesets:writeCreate, update, and delete tilesets using the Mapbox Tilesets API.
analytics:readRead and query analytics using the Mapbox Analytics API. Available for Commercial and Enterprise customers.
atlas:readRead Mapbox Atlas data and software with the Atlas installer. This scope is necessary to set up a working instance of Mapbox Atlas.

Adding URL restrictions to access tokens

An allowed URL is an absolute or partial web address to which a token grants access. There are several URL components that can be combined to make an allowed URL entry.

The following are examples of valid URL formats:

  • Domain only: mapbox.com
  • Domain with port: mapbox.com:2019
  • Protocol and domain: http://mapbox.com
  • Subdomain: docs.mapbox.com
  • Domain with path: mapbox.com/help/how-mapbox-works/access-tokens
  • Domain with query parameter: mapbox.com/?page=1

For example:

https://all-subdomains.example.com:8000/all/paths?search=foo
  • Protocol is https
  • Subdomain is all-subdomains
  • Domain is example.com
  • Port is 8000
  • Path is /all/paths
  • Search with query string parameters is ?search=foo

Notes on adding allowedUrls restrictions to a token:

  • Of the URL components listed above, only the domain is required. Protocol, subdomain, port, path, and search with query parameters are optional.
  • Paths are case sensitive.
  • If a port is not provided, ports 80 and 443 are allowed by default.
  • If no allowed URLs are provided, the token will work for requests originating from any URL.
  • Unless it is specifically added to a token, localhost will be blocked. To develop locally, create a separate token with more permissive URL restrictions.
  • If your site includes a noreferrer policy, URL restricted tokens will not work.

Rotating tokens

Any public access tokens you include in webpage will be visible to anyone who makes an effort to look for it. Access tokens can be deleted and rotated at any time if you suspect misuse. Secret tokens should only be used in places where they will not be visible to your users.

You can create as many access tokens as you want. To rotate, create a new access token, replace it in a project, and then remove the old token. Invalidation for uncached requests will happen immediately. Cached requests can take up to an hour.

Creating and managing access tokens

Mapbox account

Access tokens can be created, deleted, and managed on your Access Tokens page:

  1. Click Create a token and give your new token a name to help you remember its purpose.
  2. Specify scopes.

Example secret access token

  1. Click Create token to create the token. You may be prompted to re-enter your password.
  2. Success! Your new token will appear at the top of your list of tokens.

You can click on the name of any token to see the scopes it covers and, if the token is public, you can see the token itself.

If you created a secret access token, you will only be able to see the token in your account dashboard once - be sure to store it somewhere safe (like a password manager) if you need to access it later.

Example secret access token

Mapbox Tokens API

With the Mapbox Tokens API you can create, read, and update your access tokens. To create additional tokens using this API you will first need to create an initial token with the tokens:write scope and any scopes you want to add to the created token. To create this initial token visit your Access Tokens page, and click Create a token. Read more about the Tokens API on our API documentation page.