Token management

Join the Mapbox Developers Discord Communityarrow-right

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 account will always contain a default public access token, referred to as your default public token. When you're logged into your account, this token will automatically be embedded in example code on Mapbox.com, like this:

Sample Mapbox Geocoding API request:

https://api.mapbox.com/geocoding/v5/mapbox.places/Los%20Angeles.json?access_token= <UserAccessToken />

Your default public access token contains all public scopes (read more about public scopes below).

If you refresh and delete this token, another one will be automatically generated. You cannot add secret scopes or URL restrictions to your default public access token

Creating and managing access tokens

There are two options for creating and managing Mapbox access tokens: use the Tokens page to manage tokens using the account UI or use the Tokens API to create, list, update, and delete tokens programmatically. You can create as many access tokens as you want. We recommend creating distinct tokens for specific environments, projects, and/or client implementations to track usage on the account's Statistics page.

Mapbox Account Dashboard

Access tokens can be created, deleted, and updated on your Access Tokens page. Deleting a token is an action that cannot be reversed - token deletion is permanent. Deleted tokens or the timestamp corresponding to their deletion are not available on the Access Tokens page.

To create a new access token:

1. Click Create a token and give your new token a name to help you remember its purpose. A token's name is saved as the token's note property.
2. Specify scopes, using the principle of least privilege to only include scopes your token needs. To protect your account and your data, do not grant more scopes than necessary to each token.
3. Click Create token to create the token. You may be prompted to re-enter your password.
4. 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 (pk), you can see the token itself. If you created a secret access token (sk), 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) so you can access it later.

Mapbox Tokens API

With the Mapbox Tokens API you can create, list, update, and delete your access tokens.

The Tokens API enables you to create public pk and secret sk tokens as well as temporary tk tokens, which can support an expiration parameter up to 1 hour in the future. Note that tk tokens will not be displayed on your Access Tokens page in your account, and billable statistics generated by tk tokens will only be aggregated in the All tokens view on your Statistics page.

Get started with the Tokens API tutorial or read more on our API documentation page.

Rotating access tokens

Any access token you include on a public webpage or in source code will be visible to anyone who makes an effort to look for it. Access tokens can be deleted and replaced in your code at any time if you suspect misuse. To rotate access tokens, create a new token, replace it in your project's code, redeploy the application, and delete the older token. Invalidation for requests that have not been cached locally, in the browser, or in Mapbox infrastructure will happen immediately. The length of cached requests varies by service.

We recommend using distinct tokens for specific projects and separate client implementations to limit the number of projects you might need to update if a token has been compromised. URL restrictions can add an additional layer of security to your tokens, but have certain limitations to be aware of while implementing.

Scopes

Each access token you create will have a set of permissions that allow you or your applications to make certain types of requests to Mapbox APIs — these are called scopes. Access tokens can have either public or secret scopes. Our API documentation lists the scopes required for each Mapbox API.

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 when creating a new sk token. 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.

Read more about what each scope is for below and visit the How to Use Mapbox Securely guide for recommendations.

Public scopes

Scope	Description
styles:tiles	Read 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:read	Read styles. This is the scope that is necessary to initialize a Mapbox map style in Mapbox GL JS and our mobile Maps SDKs.
fonts:read	Read fonts. This is the scope that is necessary to generate fonts that render on your map styles and to retrieve font glyphs and ranges using the Mapbox Fonts API.
datasets:read	Read datasets. This scope is necessary for retrieving information about datasets using the Datasets API.
vision:read	Read Vision SDK services. This scope is necessary for using the Vision SDK for iOS or Android.

Secret scopes

There are a few important things to note about secret scopes before creating a secret sk token:

1. Secret scopes cannot be added to a public (pk) token. You must create a new secret (sk) token with secret scopes.
2. If you choose to add any secret scopes to a new token, you will have only one chance to view the token. Follow the instructions to copy the token and save it in a secure location, like a password manager or secret key manager.
3. Do not expose access tokens with secret scopes. Secret token API requests should never be exposed to the client. If someone else gets access to tokens with secret scopes they may be able to make changes to your account. Make all requests requiring a token with secret scopes on a server.

Scope	Description
scopes:list	List all available scopes. This scope is necessary to list all potential scopes that an account has access to using the Tokens API.
map:read	Read tilesets, tilestats, and legacy projects.
map:write	Create and update tilesets and tilestats.
user:read	Read account profile information. Use this scope to list details about your account.
user:write	Write user profile information. Use this scope to update your account information.
uploads:read	Read data uploads. This scope is necessary for tracking your upload statuses using the Mapbox Uploads API.
uploads:list	List tileset uploads. This scope is necessary for retrieving multiple upload statuses using the Mapbox Uploads API.
uploads:write	Create tileset uploads. This scope is necessary for creating an upload using the Mapbox Uploads API.
styles:write	Create and update styles. This scope is necessary for creating a style in your account using the Mapbox Styles API.
styles:list	List 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. You do not need a token with this scope to request Mapbox styles in your application. You should use separate, public tokens in your application.
styles:protect	Protect write access to styles and their assets. This scope is necessary for protecting a style using the Mapbox Styles API.
tokens:read	Read tokens. This scope is necessary to list all the tokens that belong to an account using the Mapbox Tokens API.
tokens:write	Create, update, and delete tokens. This scope is necessary to use 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:list	List datasets. This scope is necessary to list all the datasets that belong to a particular account using the Datasets API.
datasets:write	Create and update datasets using the Datasets API.
tilesets:list	List tilesets, tileset sources, and information about publishing jobs. This scope is necessary to use Mapbox Tiling Service and the Tilesets CLI.
tilesets:read	Read tilesets, tileset sources, tileset information about a publishing job, and view the global queue using Mapbox Tiling Service. This scope is necessary to use Mapbox Tiling Service and the Tilesets CLI.
tilesets:write	Create, update, publish, and delete tilesets using Mapbox Tiling Service. Create, update, replace, and delete tileset sources using Mapbox Tiling Service. Validate, update, and read tileset recipes using Mapbox Tiling Service. Update a tileset's information using Mapbox Tiling Service. This scope is necessary to use Mapbox Tiling Service and the Tilesets CLI.
downloads:read	Download the Mapbox Maps and Navigation SDKs. This scope is necessary for downloading the Maps SDK for iOS, the Maps SDK for Android, the Navigation SDK for iOS, and the Navigation SDK for Android. You do not need a token with this scope to use these SDKs. You should use separate, public tokens in your application.
vision:download	This scope is necessary for downloading the Mapbox Vision SDK. You do not need 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:read	Read 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 accounts that 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 to billable Mapbox services 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.

book

403 errors from Terminal or Postman

If you use an access token with URL restrictions to make a Mapbox API request in Terminal, Postman, or a similar tool, you will receive a 403 error since the request originated from an unauthorized URL. To run API requests in Terminal or Postman, use a token that does not have any URL restrictions.

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
• Billable services listed on the pricing page

Does not support:

• Default access tokens
• Wildcard characters
• IP addresses
• Requests from websites with a noreferrer or same-origin Referrer policy
• Requests from mobile applications built with the Mapbox Maps, Navigation, Vision SDKs
• Requests from versions of Mapbox GL JS before 0.53.1
• Requests from websites or browsers with privacy blocking extensions (including but not limited to Brave Shields and Ghostery)

Note that requests from localhost with 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.

alert

URL restriction limitations

URL restrictions are a best-effort mitigation technique to prevent your token from being used in unauthorized applications. If you believe your token is being used without consent, contact Mapbox.

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/getting-started/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
• http://example.com also authorizes http://www.subdomain2.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 from versions of Mapbox GL JS less than 0.53.1 can be denied because those requests may not include referer headers. If the account's Statistics page shows "not set", 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. Mitigate caching. Try your request in an incognito browser or on another machine, as either your device and/or the Mapbox infrastructure may have cached the response to requests made before URL restrictions were added to the token. Note that not all Mapbox services cache requests for the same length of time.
2. Confirm requests include a referer header that matches your allowed URLs. 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 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 return 403: forbidden. Review the Mapbox GL JS Referrer policy recommendations.
3. Check the website's Content Security Policy (CSP). Review the website's Content Security Policy (CSP) and the Mapbox GL JS CSP recommendations. A strict CSP could be stripping the referer headers from requests, which would result in a response of 403:forbidden.
4. Verify allowed URLs don't contain unsupported characters. Check the strings you have added to the token's allowed list for wildcard characters and/or IP addresses, which are not supported.
5. Add api.mapbox.com as an allowedURL. Depending on the 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 resolution when you include the following information with your request:

• Account ID or registered email address
• Token name or ID
• Browser(s) and versions
• Full failing API request (if possible)
• 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.

Join the Mapbox Developers Discord Communityarrow-right

Was this page helpful?