Accounts service

The Mapbox Accounts service is composed of the following APIs:

    Analytics

    Beta

    This API is available for Commercial and Enterprise plans.

    The Mapbox Analytics API returns API usage for services by resource. For example, it can calculate the number of geocoding requests that you made in one week using a specific access token.

    To use the Mapbox Analytics API, you need an access token with the analytics:read scope. To create a new secret token with the correct scope, visit your Account Dashboard. Click Create a token and select the analytics:read scope.

    Retrieve request counts

    Beta
    get
    /analytics/v1/{resource_type}/{username}/{id}?period={period}
    analytics:read

    Returns the request counts per day for the given resource, in the specified period of time.

    Required parametersDescription
    resource_typeThe resource being requested. Valid resource types are: accounts, tokens, tilesets or styles.
    usernameThe username of the account that owns the resource.
    idThe ID of the resource.
    If resource_type is:The id is:
    accountsNot required.
    tokensThe complete token.
    stylesThe style ID, which is the alphanumeric segment at the end of a style URL. (The style URL mapbox://styles/user/cimdoca6f00 contains the style ID cimdoca6f00.)
    tilesetsThe map ID.

    You can further refine the results from this endpoint with the optional period query parameter:

    Optional parametersDescription
    periodTwo comma-separated dates as ISO formatted strings. The first date must be earlier than the second, and the maximum period is one year. period is inclusive of the dates provided. The default value is the previous 90 days.

    Example request: Retrieve request counts

    # Request usage data for the user mapbox's tileset mapbox.streets during a specific 2-day period
    
    $ curl "https://api.mapbox.com/analytics/v1/tilesets/mapbox/mapbox.streets?period=2018-03-22T00:00:00.000Z,2018-03-24T00:00:00.000Z&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 request counts

    A response to the Analytics API is a JSON object that contains the following properties:

    PropertyDescription
    timestampsAn array of dates as ISO formatted strings for each day included in the response.
    periodA two-element array with the start and end dates of the response period as ISO formatted strings.
    servicesAn object with a key for each applicable service. The value for each key is an array of request counts per day in the same sequence as timestamps. Only services applicable to the given resource are returned in the response:
    Resource typeServices returned in response
    accountsmapview, static, tile, directions, geocode
    tokensmapview, static, tile, directions, geocode
    tilesetsmapview, static, tile
    stylesmapview, static, tile
    For the styles resource type, static and tile services refer to the Static API. For the tilesets resource type, static and tile services refer to the Maps API.

    Example response: Retrieve request counts

    {
        "period": ["2016-03-22T00:00:00.000Z", "2016-03-24T00:00:00.000Z"],
        "timestamps": ["2016-03-22T00:00:00.000Z", "2016-03-23T00:00:00.000Z", "2016-03-24T00:00:00.000Z"],
        "services": {
            "mapview": [ 25, 22, 37 ],
            "static": [ 23, 20, 34 ],
            "tiles": [ 30, 39, 53 ]
        }
    }
    

    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.
    allowedUrls
    Beta
    An 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.
    allowedUrls
    Beta
    URLs 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
    
    $ 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 temp 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, or both, 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.
    allowedUrls
    Beta
    Update the restricted token's allowed URLs.

    Example request: Update a token

    # Update a token to have fonts:read scope
    
    $ 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.