How to protect your API key

If you publish a map, you are also exposing your API key. There are several ways to protect your key and prevent misuse, and we describe them in detail on this page.

By default, your API keys are not secured. To apply any of the protection methods described here, you can either edit the existing keys, or create a new key.

Allow map usage only on listed websites

If the map is only published on certain websites, list these websites in the Allowed HTTP origins field. For example, enter mydomain.com to ensure that only requests coming from mydomain.com get processed. To allow requests from subdomains, use *.mydomain.com. Put each rule on a separate line.

Make sure your applications send the Origin (or Referer) header, otherwise the requests will be treated as “unknown” and will be rejected if any origin is specified here. You can use the ? placeholder to explicitly allow unknown origins. Requests with the Origin header coming from a domain that is not on this list will still be rejected.

Allow map usage only in listed software

For other usage where the map is not used on a specific URL, like in mobile apps or desktop GIS software, you can whitelist software with a specific User-Agent. Only this software will be then able to use the map.

In the Allowed User-Agent header field, fill in a substring of your software’s User-Agent. Note the field is case-sensitive. The saved substring gets compared with the User-Agent HTTP header of each request, and if there is a match, the request is processed. Otherwise, it is denied. 

Combining protection methods

It is possible to add both restrictions to a single API key. In that case, we apply a strict AND logic: The API request succeeds only if it matches both the allowed HTTP origin and User-Agent simultaneously.

Best practice: Create a separate API key for each platform. Because web browsers and mobile apps send different types of headers, combining protection methods on a single key will usually block legitimate requests. Instead, use one key protected by HTTP origin for your website, and another key protected by a User-Agent for your mobile or desktop app.

Use digital signature instead of API key

Extra tip: If the code of your application isn’t public, you can prevent misuse completely by securing API requests with a digital signature rather than using API keys. This is especially practical for mobile and desktop apps, or enterprise applications calculating signature for every map tile request.

What’s next

To secure your API key with the described restrictions, go to your MapTiler account, page API keys and click Edit next to the key you want to secure. Alternatively, click New key to create a key and secure it in one step.