This API is available for developer preview and may be changed or removed at any time without notice.

Tokens

You can use the Tokens API to generate short-lived tokens that are useful in situations where normal tokens, which are supplied by authorizations, are impractical. The API is private, which means it is only accessible via the private API proxy service located at https://www.mapbox.com/core and must be accessed using a valid mapbox.com session cookie.

Create a temporary token

Request a temporary token that will expire one hour in the future.

GET https://www.mapbox.com/core/tokens/v1

{
    "token": "<token>"
}

The token can be used to authenticate requests against most endpoints on the primary Mapbox API, https://api.mapbox.com, for as long as the token is valid. The token should not be used to authenticate requests against the private API proxy service as unexpected behavior may occur.

Critical endpoints require fresh tokens and will reject requests with HTTP 401 even if token has not yet expired. In these cases, clients should prompt the user for password authentication, request a new token using this API, and attempt the original request again.

You can inspect the token payload using a tool like jwt.io. An example payload looks like this:

{
  "u": "example",
  "exp": 1441322205,
  "iat": 1441318605,
  "scopes": [
    "essentials",
    "scopes:list",
    "map:read",
    "map:write",
    "user:read",
    "user:write"
  ],
  "client": "mapbox.com"
}
Claim Description
u Identifier for the Mapbox account that generated the token.
exp Expiration time expressed as a UNIX timestamp in seconds.
iat Issued-at time expressed as a UNIX timestamp in seconds. Some endpoints require fresh tokens and will reject requests even if token has not yet expired.
scopes Scopes carried by the token. By default, this is all available scopes for an account.
client The client for which the token was generated.

Limiting token scopes

By default, a token will include all available scopes for that account. You can request only specific scopes to create a less powerful token.

To restrict the token’s scopes, add a scopes query string parameter with a comma separated list of valid scopes. Only scopes that the account can access can be added to the token.

GET https://www.mapbox.com/core/tokens/v1?scopes=user:read,user:write

{
    "token": "<token>"
}