How to use Credentials to securely sign requests to MapTiler API

This article describes how to sign requests to the MapTiler API with tokens. Using tokens is a much more secure way of authorizing requests to your MapTiler account. Choose this method when the standard authorization method, API keys, is not sufficiently strong enough.

How do secure credentials work?

Each request is cryptographically signed when using the credentials, so using the same signature for a different request is impossible. This makes it impossible to steal the credentials during transmission and prevents any misuse of credentials.

How to use credentials

In MapTiler administration, under Account > Credentials, create new credentials and copy the token (keep this token private – treat it the same way as a password).

When using the credentials, every request to the MapTiler API has to contain key and signature query parameters.

How to calculate the signature

• The token from Cloud has two parts separated with an underscore: key_secret
• Use “key” directly as key in the query
• Calculate signature:
  • Decode “secret” (encoded as hexadecimal) to get the binary secret value
  • Sign the whole URL (including “key”) using HMAC SHA256
  • Add &signature= as the last query parameter (URL-safe Base64 encoded)

Python code

This function is an example of how you can handle URL parameter formatting and append the signature. You can implement the logic in any other language if needed.

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