Accounts service

The Mapbox Accounts service is composed of the following APIs:

    Analytics

    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 were made in a week with 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

    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

    # 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 seamlessly. The following SDK is available for this endpoint:

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

    Retrieve counts response

    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

    {
        "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.
    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",
      "token": "pk.eyJ1Ijoic2NvdGhpcyIsImEiOiJjaWp1Y2ltYmUwMDBicmJrdDQ4ZDBkaGN4In0.sbihZCZJ56-fsFNKHXF8YQ"
    }
    

    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

    $ 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 seamlessly. The following SDK is available for this endpoint:

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

    List tokens response

    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

    [
      {
        "client": "api",
        "note": "a public token",
        "usage": "pk",
        "id": "cijucimbe000brbkt48d0dhcx",
        "default": false,
        "scopes": ["styles:read", "fonts:read"],
        "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.

    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 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"]}' '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 seamlessly. The following SDK is available for this endpoint:

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

    Create a token response

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

    Example response

    {
      "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",
      "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

    # 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 seamlessly. The following SDK is available for this endpoint:

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

    Example request body

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

    Create a temporary token response

    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

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

    Request body

    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.

    Example request

    # Update a token to have fonts:read scope
    
    $ curl -H 'Content-Type: application/json' -X PATCH -d '{"scopes": ["styles:read", "fonts:read"]}' '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 seamlessly. The following SDK is available for this endpoint:

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

    Update a token request response

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

    Example response

    {
      "client": "api",
      "note": "My top secret project",
      "usage": "pk",
      "id": "cijucimbe000brbkt48d0dhcx",
      "default": false,
      "scopes": ["styles:tiles", "styles:read", "fonts:read"],
      "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

    $ 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 seamlessly. The following SDK is available for this endpoint:

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

    Update a token request response

    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

    $ 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 seamlessly. The following SDK is available for this endpoint:

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

    Retrieve a token response

    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

    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

    $ 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 seamlessly. The following SDK is available for this endpoint:

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

    List scopes response

    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)

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

    Tokens API restrictions and limits

    • Requests must be made over HTTPS. HTTP is not supported.
    • The Tokens API is limited to 120 requests per minute per account.