Token management

Your Tokens page is where you can manage access tokens for your Mapbox account. To access the Tokens page, log into your account and navigate to account.mapbox.com/tokens.

Default public access token

Your default public access token contains all public scopes (read more about public scopes below). Your account will always contain a default public access token. If you delete this token, another one will be automatically generated. You cannot add secret scopes or domain restrictions to your default public access token.

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. Read more about what each scope is for below and visit the How to Use Mapbox Securely guide for recommendations.

Public scopes

ScopeDescription
styles:tilesRead style as PNG tiles and static images. This is the scope that is necessary for retrieving a static map from a style with the Static Images API or for retrieving raster tiles from a style with the Static Tiles 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.
vision:readRead Vision SDK services. This scope is necessary for using the Vision SDK for iOS or Android.

Secret scopes

There are two important things to note about secret scopes before adding them to an access token:

  1. If you choose to add any secret scopes to your token, you will have only one chance to view the token.
  2. Do not expose access tokens with secret scopes. If someone else gets access to tokens with secret scopes they may be able to make changes to your account. Keep tokens with secret scopes secret.
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.
vision:downloadDownload the Vision SDK. This scope is necessary for downloading the Vision SDK. You do not need this a token with this scope to use the Vision SDK. You should use a separate, public token in your application with the public vision:read scope.
atlas:readRead Mapbox Atlas data and software with the Atlas installer. This scope is necessary to set up a working instance of Mapbox Atlas. This scope is only available to users who have access to Atlas.

Questions about scopes? Contact support.

URL restrictions

You can make your access tokens more secure by adding URL restrictions from the account dashboard tokens page or with the Tokens API. When you add URL restrictions to a token, that token will only work for requests that originate from the URLs you specify. Requests from unauthorized URLs will return status code 403: Forbidden.

Tokens without restrictions will work for requests originating from any URL.

Requirements and limitations

This feature is compatible with many Mapbox tools with some limitations.

Supports:

  • API requests that include a referer header
  • Versions of Mapbox GL JS greater than or equal to 0.53.1
  • Up to 100 distinct URL restrictions per token

Does not support:

  • Default access tokens
  • Requests from mobile applications built with the Mapbox Maps, Navigation, Vision SDKs
  • Requests from versions of Mapbox GL JS prior to 0.53.1
  • Requests from websites with some privacy blocking browser extensions
  • Requests from websites with a noreferrer policy
  • Requests from localhost from a restricted token will be blocked unless localhost is specifically added to a token's allowed list. To develop locally, we recommend creating a separate token with more permissive URL restrictions.
  • Wildcard characters

Questions about the capabilities of URL restrictions? Contact support.

Add URL restrictions to access tokens

An allowed URL is an absolute or partial web address to which a token grants access. If no allowed URLs are provided, the token will work for requests originating from any URL. Depending on your use case, you might need to add api.mapbox.com to your access token's allowed list.

There are several URL components that can be combined to make an allowed URL entry.

Example URL structure:

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

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

Matching rules:

  • Only a domain is required for the URL restriction
  • 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.

Example scenarios

Subdomains of any allowed URLs are also allowed:

  • http://example.com also authorizes http://www.example.com
  • http://example.com also authorizes http://www.production.example.com

Subpaths of an allowed path are also allowed. Paths are case-sensitive:

  • http://example.com also authorizes http://example.com/anything/else
  • http://example.com/path also authorizes http://example.com/path/more
  • http://example.com/path does not authorize http://example.com/another/path
  • http://example.com/path does not authorize http://example.com/Path

If a protocol is specified it must be matched:

  • http://example.com does not authorize https://example.com

If no protocol is specified, then any protocol is acceptable:

  • example.com also authorizes http://example.com and https://example.com

Troubleshooting URL restrictions

Why don't all versions of Mapbox GL JS support URL restrictions?

Requests originating from earlier versions of Mapbox GL JS than 0.53.1will be denied because those requests will not include referer headers. If your Statistics page shows "not set", you need to upgrade GL JS versions before adding URL restrictions to an access token.

What steps can I take if my URL restrictions aren't working, and I don't know why?

There are a few troubleshooting steps you can take to try and resolve common issues:

  1. Try your request in an incognito browser or on another machine, as either your device and/or the Mapbox infrastructure may have cached your previous request. Note that not all Mapbox services cache requests for the same length of time.
  2. Open your browser's developer tools and inspect the requests in the network tab. Look to make sure the referer header of the live requests matches the URL that you expect it to and have added to your tokens allowed list. If the request does not have a referer header (it's blank), requests from that URL with a restricted token will be blocked.
  3. Check the strings you have added to the token's allowed list for wildcard characters, which are not supported.
  4. Depending on your use case, you might need to add api.mapbox.com to your access token's allowed list. For example, if you are generating a URL with the Mapbox Studio Share Button or using an iFrame that points to api.mapbox.com, with a restricted token, you should include api.mapbox.com on the token's allowed list.

If I cannot resolve my issue, what information should I include in my support request?

We're happy to help with your questions. We can provide the most prompt service when you include the following information with your request:

  • Account ID or registered email address
  • Token name or ID
  • Browser(s)
  • Full failing API request
  • Screenshot of a failing request, including the referer header of the request (with developer tools / inspect)
  • Description of expected behavior, actual behavior, and things you have tried to mediate the situation

We'll try to diagnose the issue and provide tips that help you produce the desired behavior.

Was this page helpful?