Service token

A service token is the more secure alternative to an API key. You can use it in two distinct ways:

  • To call the Service API: As a plain Authorization header to access your MapTiler account and manage your map data programmatically. See the Service API reference for details.
  • To call the public API: To cryptographically sign each request from your backend, providing much stronger security than an API key. Described on this page.

Get your service token

  1. Go to the Credentials page in your account.
  2. Click New credential to create a service token, and copy it.

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.

How signing works

Each API 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 service token far harder to misuse than 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:

  1. The token consists of two parts separated by an underscore: <key>_<secret>. Split your token into these two parts.
  2. Add key to your request as the key query parameter.
  3. Decode secret from hexadecimal to get the binary secret, then sign the full URL, including the key parameter, using HMAC-SHA256 with that secret.
  4. 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}"
Was this helpful?