Accounts service

The Mapbox Accounts service is composed of the following APIs:

    Tokens

    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 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.

    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-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:

    PropertyDescription
    idThe token's unique identifier.
    usageThe type of token. One of: pk (public), sk (secret), or tk (temporary).
    clientThe client for the token. This is always api.
    defaultIndicates whether the token is a default token.
    scopesAn array that contains the scopes granted to the token.
    noteA human-readable description of the token.
    createdThe date and time the token was created.
    modifiedThe date and time the token was last modified.
    allowedUrlsAn array that contains the URLs that the token is restricted to.
    tokenThe 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
    /tokens/v2/{username}
    tokens:read

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

    Required parameterDescription
    usernameThe username of the account for which to list tokens.

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

    Optional parametersDescription
    defaultIf this parameter is set to true, the response will only include the account's default token. If this parameter is set to false, the response will include all of the account's tokens except for the default token.
    limitThe maximum number of tokens to return.
    sortbySort the tokens in the response by their created or modified timestamps.
    startThe token after which to start the listing. The token key is found in the Link header of a response. See the pagination section for details.
    usageUse 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/{username}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    Endpoint support

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

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

    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"
      }
    ]
    

    Create a token

    post
    /tokens/v2/{username}
    tokens:write

    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.

    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 parameterDescription
    usernameThe username of the account for which to list scopes.

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

    ParameterDescription
    noteCreate a description for the token.
    scopesSpecify 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.
    allowedUrlsURLs that this token is allowed to work with.

    Available token scopes

    The scopes included in the token decide whether the token is public or secret. A public token may only contains public scopes, while a secret token can contain both public and secret scopes.

    • Public tokens: styles:tiles, styles:read, fonts:read, datasets:read
    • Secret tokens: scopes:list, map:read, map:write, user:read, user:write, uploads:read, uploads:list, uploads:write, styles:write, styles:list, tokens:read, tokens:write, datasets:list, datasets:write, tilesets:list, tilesets:read, tilesets:write, analytics:read (if user has a Commercial or Enterprise account)

    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/{username}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    '
    Endpoint support

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

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

    Response: Create a token

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

    Example response: Create a token

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

    Create a temporary token

    post
    /tokens/v2/{username}
    tokens:write

    Creates a new temporary token that automatically expires at a set time. You can create a temporary token using a public or a secret token, or using another temporary token. Temporary tokens can't be updated or revoked after they are created.

    Required parameterDescription
    usernameThe username of the account for which to list scopes.

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

    Request body propertiesDescription
    expiresSpecify when the temporary token will expire. Cannot be a time in the past or more than one hour in the future. If the authorizing token is temporary, the expires time for the new temporary token cannot be later than that of the authorizing temporary token.
    scopesSpecify the scopes that the new temporary token will have. The authorizing token needs to have the same scopes as, or more scopes than, the new temporary token you are creating.

    Example request: Create a temporary token

    # Request a temporary token with "styles:read" and "font:read" scopes
    
    $ curl -H "Content-Type: application/json" -X POST -d '{"expires": "2018-09-20T06:30:00Z","scopes": ["styles:read", "fonts:read"]}' 'https://api.mapbox.com/tokens/v2/{username}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    '
    Endpoint support

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

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

    Example request body: Create a temporary token

    {
      "expires": "2016-09-15T19:27:53.000Z",
      "scopes": ["styles:read", "fonts:read"]
    }
    

    Response: Create a temporary token

    The response body for a successful request will be a new temporary token. Unlike public and secret tokens, a temporary token contains its metadata inside the payload of the token instead of referencing a metadata object that persists on the server.

    Example response: Create a temporary token

    {
      "token": "tk.eyJ1IjoibWFwYm94IiwiZXhwIjoxNDczOTY3NjczLCJpYXQiOjE0NzM5Njc2NDMsInNjb3BlcyI6WyJzdHlsZXM6cmVhZCIsImZvbnRzOnJlYWQiXSwiY2xpZW50IjoiYXBpIn0.ZepsWvpjTMlpePE4IQBs0g"
    }
    

    Update a token

    patch
    /tokens/v2/{username}/{token_id}
    tokens:write

    Update the note, the scopes, the allowedUrls, or all three in a token's metadata. When updating scopes for an existing token, the token sent along with the request must also have the scopes you're requesting. It is not possible to create a token with access to more scopes than the token that updated it.

    Required parameterDescription
    token_idThe ID of the token that you want to update.

    The request body must be a JSON object that contains one or both of the following properties:

    Request body propertiesDescription
    noteUpdate the token's description.
    scopesUpdate the token's scopes. The authorizing token needs to have the same scopes as, or more scopes than, the token you are updating. A public token may only be updated to include other public scopes. A secret token may be updated to contain public and secret scopes.
    allowedUrlsUpdate the restricted token's allowed URLs.

    Example request: Update a token

    # Update a token to have "fonts:read" scope and a "https://docs.mapbox.com" allowed URL
    
    $ curl -H 'Content-Type: application/json' -X PATCH -d '{"scopes": ["styles:read", "fonts:read"], "allowedUrls": ["https://docs.mapbox.com"]}' 'https://api.mapbox.com/tokens/v2/{username}/{token_id}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    '
    Endpoint support

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

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

    Response: Update a token

    The response body for a successful request will be a new temporary token.

    Example response: Update a token

    {
      "client": "api",
      "note": "My top secret project",
      "usage": "pk",
      "id": "cijucimbe000brbkt48d0dhcx",
      "default": false,
      "scopes": ["styles:tiles", "styles:read", "fonts:read"],
      "allowedUrls": ["https://docs.mapbox.com"],
      "created": "2016-01-25T19:07:07.621Z",
      "modified":"2016-01-25T19:07:07.621Z",
      "token": "pk.eyJ1Ijoic2NvdGhpcyIsImEiOiJjaWp1Y2ltYmUwMDBicmJrdDQ4ZDBkaGN4In0.sbihZCZJ56-fsFNKHXF8YQ"
    }
    

    Delete a token

    delete
    /tokens/v2/{username}/{token_id}
    tokens:write

    Delete an access token. This will revoke its authorization and remove its access to Mapbox APIs. Applications using the revoked token will need to get a new access token before they can access Mapbox APIs.

    Note that cached resources may continue to be accessible for a little while after a token is deleted. No new or updated resources will be accessible with the deleted token.

    Required parameterDescription
    token_idThe ID of the token that you want to delete.

    Example request: Delete a token

    $ curl -X DELETE "https://api.mapbox.com/tokens/v2/{username}/{token_id}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    Endpoint support

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

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

    Response: Delete a token

    HTTP 204

    Retrieve a token

    get
    /tokens/v2?access_token={access_token}

    Retrieve an access token and check whether it is valid. If the token is invalid, an explanation is returned as the code property in the response body.

    Required parameterDescription
    access_tokenThe access token to retrieve.

    Example request: Retrieve a token

    $ curl "https://api.mapbox.com/tokens/v2?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
    
    Endpoint support

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

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

    Response: Retrieve a token

    The body of the token is parsed and included as the token property in object form. The returned object contains the following properties:

    PropertyDescription
    codeIndicates whether the token is valid. If the token is invalid, describes the reason. One of:
    CodeDescription
    TokenValidThe token is valid and active.
    TokenMalformedThe token cannot be parsed.
    TokenInvalidThe signature for the token does not validate.
    TokenExpiredThe token was temporary and has expired.
    TokenRevokedThe token's authorization has been deleted.
    tokenThe token object. Contains the following properties:
    token.usageThe token type. One of pk, sk, or tk.
    token.userThe user to whom the token belongs.
    token.authorizationThe token's unique identifier.
    token.expirestk tokens only. The expiration time of the token.
    token.createdtk tokens only. The creation time of the token.
    token.scopestk tokens only. The token's assigned scopes.
    token.clienttk tokens only. Always "api".

    Example response: Retrieve a token

    For a public token:

    {
      "code": "TokenValid",
      "token": {
        "usage": "pk",
        "user": "mapbox",
        "authorization": "cijucimbe000brbkt48d0dhcx"
      }
    }
    

    For a temporary token:

    {
      "code": "TokenExpired",
      "token": {
        "usage": "tk",
        "user": "mapbox",
        "expires": "2016-09-15T19:27:53.000Z",
        "created": "2016-09-15T19:27:23.000Z",
        "scopes": ["styles:read", "fonts:read"],
        "client": "api"
      }
    }
    

    List scopes

    get
    /scopes/v1/{username}?access_token={access_token}
    scopes:list

    List scopes for a user. All potential scopes a user has access to are listed.

    Public tokens may only contain scopes with the public property set to true. Secret tokens may contain any scope.

    Required parameterDescription
    usernameThe username of the account for which to list scopes.

    Example request: List scopes

    $ curl "https://api.mapbox.com/scopes/v1/{username}?access_token=
    YOUR_MAPBOX_ACCESS_TOKEN
    "
    Endpoint support

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

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

    Response: List scopes

    The response body will contain an object for each scope the user has access to, each with the following properties:

    PropertyDescription
    idThe identifier of the scope.
    descriptionA description of permissions granted by the scope.
    publictrue if the scope is available for public tokens.

    Example response (truncated): List scopes

    [
      {
        "id": "scopes:list",
        "description": "List all available scopes."
      },
      {
        "id": "styles:read",
        "public": true,
        "description": "Read styles."
      }
    ]
    

    Tokens API restrictions and limits

    • Requests must be over HTTPS. HTTP is not supported.
    • The Tokens API is limited to 100 requests per minute per account.
    • Each token is limited to 100 allowed URLs.
    • Temporary tokens cannot have allowed URLs, but public tokens and secret tokens can.
    Was this section on Tokens helpful?