Service token

A service token gives your backend, scripts, and tools access to MapTiler. Unlike an API key, it must always stay private.

Get your service token

In your MapTiler account, go to Credentials.
Click New service token and give the token a name.
In the token’s menu, select Copy token.

Warning

Never expose a service token in code or environments visible to others, such as a client-side web app. Keep it private and treat it the same way you’d treat a password. If your app’s source code is exposed, always use an API key.

Use your token

How you use the token depends on what you’re doing:

Using MapTiler CLI or Upload JS? Pass the token to the tool as its documentation describes. The tool handles the rest, so there’s nothing to sign.
Calling the Service API directly? Send the token in the Authorization: Token YOUR_SERVICE_TOKEN header. There’s nothing to sign either.
Calling MapTiler’s public APIs from your backend? Sign each request with the token instead of sending it, as described on this page.

Sign public API requests

Use this only when you call MapTiler’s public APIs from your backend and want stronger security than an API key gives you. Each request gets a unique cryptographic signature, computed from the request itself. This means that a captured signature can’t be reused for a different request, making a signed request far harder to misuse than one with an API key.

Build a signed request

Every signed request needs a key and a signature query parameter. Here’s the logic you need to set up on your backend to make it work:

The token consists of two parts separated by an underscore: <key>_<secret>. Split your token into these two parts.
Add key to your request as the key query parameter.
Decode secret from hexadecimal to get the binary secret, then sign the full URL, including the key parameter, using HMAC-SHA256 with that secret.
Base64 URL-safe encode the resulting signature, and append it as the last query parameter: &signature=....

Warning

Encode any unsafe characters in your URL (for example, spaces as %20) before computing the signature, not after. The browser or HTTP client you use might encode the URL for you when sending the request, and if that differs from what you signed, the signature won’t match.

Python example

Here’s an example of how you can handle URL parameter formatting and append the signature. You can implement the logic in any language you prefer.


import base64
import hashlib
import hmac

def sign_url(input_url: str, token: str) -> str:
    key, _, encoded_secret = token.partition("_")

    # Select correct parameter delimiter
    delimiter = "&" if "?" in input_url else "?"
    keyed_url = f"{input_url}{delimiter}key={key}"

    # Decode hexadecimal secret to binary
    decoded_secret = base64.b16decode(encoded_secret, casefold=True)

    # Calculate HMAC-SHA256 signature
    signature = hmac.new(
        decoded_secret, keyed_url.encode("utf-8"), hashlib.sha256
    )
    encoded_signature = base64.urlsafe_b64encode(signature.digest()).decode(
        "utf-8"
    )

    # Return full signed URL
    return f"{keyed_url}&signature={encoded_signature}"

Join us online - 19th of November