Creating access tokens with the Tokens API | Help

Prerequisite

Familiarity with APIs and using the command line.

This guide will walk through how to create access tokens with the Tokens API using cURL. After reading this tutorial, you will be able to create appropriately scoped access tokens with the Tokens API using cURL.

Getting started

You will need the following to get started:

Mapbox account. Sign up for free at mapbox.com/signup.
Experience using APIs and the command line with cURL.

Decide on your token scopes

Access tokens are keys required in every request to the Mapbox APIs. All token have one or more token scopes that set the permissions for the token, allowing that token to interact with allowed APIs for specified tasks. Each service section in the API documentation lists the scopes required for various request types:

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 interact with the Mapbox Tiling Service, select the tilesets:write , tilesets:read, and/or tilesets:list scopes, depending on the operation(s) that will be performed with the token. To display a map in a web or mobile application, create a separate access token that does not include secret scopes - but does include the public styles:read and fonts:read scopes - to abide by the principle of least privilege.

Note

When you create a new token, some of the scope options are secret scopes. If you add one or more secret scopes to a new token, it will be a secret token. You can only view secret tokens once on the Tokens page, at the time when you create them. It's important to copy the new secret token and save it in a secure place.

Create a token that can create tokens

The authorizing token must have the tokens:write scope, as well as all the scopes you want to add to the new tokens. To create the authorization token, visit your Tokens page, and click Create a token.

Note

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.

Make the token using the command line

Public tokens

Public tokens only have public scopes. In your command line, you can create a public token by using this command:


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

Note: The access token used in the request above must have the token scope of tokens:write.

Navigate to your Tokens page to see the new token in your account!

Secret tokens

To create a token with secret scopes for interacting with the Mapbox Tiling Service, your command may look like this:


$curl -H "Content-Type: application/json" -X POST -d '{"note": "MTS token","scopes": ["styles:tiles", "styles:read", "fonts:read", "datasets:read", "tilesets:read", "tilesets:write", "tilesets:list"]}' 'https://api.mapbox.com/tokens/v2/YOUR_MAPBOX_USERNAME?access_token=YOUR_MAPBOX_ACCESS_TOKEN'

The response will look something like this:


{
  "client": "api",
  "note": "Uploads token",
  "usage": "sk",
  "id": "cjo6jcmxn0l3x3vqmdr4epqk8",
  "default": false,
  "scopes": [
    "styles:tiles",
    "styles:read",
    "fonts:read",
    "datasets:read",
    "tilesets:read",
    "tilesets:write",
    "tilesets:list"
  ],
  "created": "2018-11-07T02:19:53.538Z",
  "modified": "2018-11-07T02:19:53.538Z",
  "token": "{new_access_token}"
}

Secret tokens will not be available on the Tokens page after they have been created. Be sure to copy and store the full token in a secure location when the creation succeeds.

Finished product

You have created an authorizing access token that can create new tokens, and used the authorizing token to create a new token with the correct scopes using the Tokens API.