Tokens | API Docs

An access token provides access to Mapbox resources on behalf of a user. The Mapbox Tokens API provides you with a programmatic way to create, update, delete, and retrieve tokens, as well as list a user's tokens and token scopes.

All user accounts have a default public token. Additional tokens can be created to grant additional, or more limited, privileges.

The actions allowed by a token are based on scopes. A scope is a string that often is a resource type and action separated by a colon. For example, the styles:read scope allows read access to styles. Tokens will have access to different scopes depending on their account level and other features of their account.

To learn more about token basics, like creating a token, see our Getting Started with Access Tokens guide.

Token format

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.

Header. A literal value of either pk (public token), sk (secret token), or tk (temporary token).
Payload. A base64-URL-encoded JSON object containing the identity and authorities of the token. pk and sk tokens contain a reference to metadata that holds the rights granted for the token. tk tokens contain the contents of the metadata directly in the payload.
Signature. Signed by Mapbox and used to verify the token has not been tampered with.

Token metadata object

Every token has a metadata object that contains information about the capabilities of the token. The token metadata object contains the following properties:

Property	Type	Description
`id`	`string`	The token's unique identifier. This is not the access token itself, but rather an identifier for a specific `pk`, `sk`, or `tk` token. You can find a token's ID within the account dashboard by navigating to the token's page, clicking on the token's name, and copying the value at the end of the URL, like: `https://account.mapbox.com/access-tokens/<token_id>`
`usage`	`string`	The type of token. One of: `pk` (public), `sk` (secret), or `tk` (temporary).
`client`	`string`	The client for the token. This is always `api`.
`default`	`boolean`	Indicates whether the token is a default token.
`scopes`	`array`	An array that contains the scopes granted to the token.
`note`	`string`	A human-readable description of the token.
`created`	`string`	The date and time the token was created.
`modified`	`string`	The date and time the token was last modified.
`allowedUrls`	`array`	The URLs that the token is restricted to.
`token`	`string`	The token itself.

Example token metadata object


{
  "id": "cijucimbe000brbkt48d0dhcx",
  "usage": "pk",
  "client": "api",
  "default": false,
  "note": "My website",
  "scopes": ["styles:read", "fonts:read"],
  "created": "2018-01-25T19:07:07.621Z",
  "modified": "2018-01-26T00:39:57.941Z",
  "allowedUrls": ["https://docs.mapbox.com"],
  "token": "pk.eyJ1Ijoic2NvdGhpcyIsImEiOiJjaWp1Y2ltYmUwMDBicmJrdDQ4ZDBkaGN4In0.sbihZCZJ56-fsFNKHXF8YQ"
}

Support for allowed URLs

The allowed URLs feature is compatible with many Mapbox tools, with some limitations. For web applications using Mapbox GL JS, it requires version 0.53.1+. It is not compatible with Mapbox native SDKs. Adding a URL restriction to a token makes it unusable by a mobile application. A separate token should be maintained for mobile applications.See the Adding URL restrictions to access tokens guide to learn more about this feature for web requests.

List tokens

get

https://api.mapbox.com/tokens/v2/{username}

tokens:read

token scope

List all the tokens that belong to an account. This endpoint supports pagination.

Required parameter	Type	Description
`username`	`string`	The username of the account for which to list tokens.

You can further refine the results from this endpoint with the following optional parameters:

Optional parameter	Type	Description
`default`	`boolean`	If this parameter is `true`, the response will only include the account's default token. If this parameter is `false`, the response will include all the account's tokens except for the default token.
`limit`	`integer`	The maximum number of tokens to return.
`sortby`	`string`	Sort the tokens in the response by their `created` or `modified` timestamps.
`start`	`string`	The token after which to start the listing. Find the token key in the `Link` header of a response. See the pagination section for details.
`usage`	`string`	Use this parameter to return either only public tokens (`pk`) or secret tokens (`sk`). By default, this endpoint returns both types of token.

Example request: List tokens


$curl "https://api.mapbox.com/tokens/v2/YOUR_MAPBOX_USERNAME?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"

Response: List tokens

The response body will contain all the tokens that belong to the username specified in the query, each containing the properties described in the token metadata object section.

If a listed token's usage property is sk, the token property will not be included in the response.

Example response: List tokens


[
  {
    "client": "api",
    "note": "a public token",
    "usage": "pk",
    "id": "cijucimbe000brbkt48d0dhcx",
    "default": false,
    "scopes": ["styles:read", "fonts:read"],
    "allowedUrls": ["https://docs.mapbox.com", "https://account.mapbox.com"],
    "created": "2016-01-25T19:07:07.621Z",
    "modified": "2016-01-26T00:39:57.941Z",
    "token": "pk.eyJ1Ijoic2NvdGhpcyIsImEiOiJjaWp1Y2ltYmUwMDBicmJrdDQ4ZDBkaGN4In0.sbihZCZJ56-fsFNKHXF8YQ"
  },
  {
    "client": "api",
    "note": "a secret token",
    "usage": "sk",
    "id": "juorumy001cutm5r4fl2y1b",
    "default": false,
    "scopes": ["styles:list"],
    "created": "2016-01-26T00:50:13.701Z",
    "modified": "2016-01-26T00:50:13.701Z"
  }
]

Supported libraries: List tokens

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDK supports this endpoint:

Mapbox JavaScript SDK

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

Create a token

post

https://api.mapbox.com/tokens/v2/{username}

tokens:write

token scope

Creates a new token. 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.

To create additional tokens using the Mapbox Tokens API, you need to have an authorizing token that has the tokens:write scope, as well as all the scopes you want to add to the newly created token. To create the authorization token, visit your Account Dashboard, and click Create a token.

Note that while it is possible to create a token with no scopes, you will not be able to update this token later to include any scopes.

Required parameter	Type	Description
`username`	`string`	The username of the account for which to list scopes.

The request body must be a JSON object that contains the following properties:

Parameter	Type	Description
`note`	`string`	Create a description for the token.
`scopes`	`array`	Specify the scopes that the new token will have. The authorizing token needs to have the same scopes as, or more scopes than, the new token you are creating.
`allowedUrls`	`array`	URLs that this token is allowed to work with.

Available token scopes

The scopes included in the token determine whether the token is public or secret. A public token can only contain public scopes, while a secret token can contain both public and secret scopes. For a full list of all public and secret scopes, see the Token management documentation.

Example request: Create a token


# Create a public token with "styles:read" and "fonts:read" scopes and a "https://docs.mapbox.com" allowed URL

$curl -H "Content-Type: application/json" -X POST -d '{"note": "My top secret project","scopes": ["styles:read", "fonts:read"], "allowedUrls": ["https://docs.mapbox.com"]}' 'https://api.mapbox.com/tokens/v2/YOUR_MAPBOX_USERNAME?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN'

Response: Create a token

The response body for a successful request will be a new public or secret token.

Token format​

Token metadata object​

Example token metadata object​

List tokens​

Example request: List tokens​

Response: List tokens​

Example response: List tokens​

Supported libraries: List tokens​

Create a token​

Available token scopes​

Example request: Create a token​

Response: Create a token​

Example response: Create a token