API key

An API key is a unique code that tells our services who’s making the request, so we know it’s your website or application asking for a map. For example, this request loads our Streets map:

https://api.maptiler.com/maps/streets-v4/?key=YOUR_MAPTILER_API_KEY_HERE#1.0/0.00000/0.00000

Replace YOUR_MAPTILER_API_KEY_HERE with a valid key and open the URL in your browser to see the map. Without a valid key, the request fails.

Get your API key

Getting a MapTiler API key is free of charge, and you can go back to copy it anytime.

1. Go to the API keys page in your MapTiler account.
2. Click New key. Or if you want to use an existing key, click Edit next to the key.
3. Secure the key by adding either Allowed User-Agent header or Allowed HTTP origin, depending on your use case (see below).
4. Save the changes and copy the key to have it ready.

Secure your key by use case

A new API key has no security applied. If you use it publicly without securing it, anyone can steal it. To prevent this, secure your key based on where and how you use it.

Simple map embedding

To add a map to a website or blog post, secure the key with Allowed HTTP origin – that’s the website where the map will be displayed.

Example: If you plan to add a map with your shop locations to the page https://my-amazing-shop.com/contacts, enter the web domain my-amazing-shop.com.

Secure the key right before you publish the map. While you’re still testing, keep it unsecured if you preview the map by opening the HTML file directly from your computer (the address bar starts with file://). Files opened this way don’t send any origin, so a secured key would block the map.

After you secure the key, it will only load the map on the actual website you provided as the allowed origin. If someone steals your key, it won’t work for them.

Web application

For use in web app frontend, secure the key with Allowed HTTP origins in the key’s settings:

• List the domains your app runs on, for example mydomain.com, one per line.
• Use the wildcard (asterisk) *.mydomain.com to also allow subdomains.

Listing ? as an allowed origin will accept requests with no Origin header. This is close to not securing the key at all and shouldn’t be used without a specific reason.

Local testing

While developing, your local dev server sends its own origin, typically http://localhost:<port> or http://127.0.0.1:<port> depending on your setup. These are technically two different origins, so use whichever one your dev server actually runs on. Enter it without port and protocol: localhost or 127.0.0.1.

If you’re opening the HTML file directly (file://) rather than running a local server, see Simple map embedding.

Staging and production

If you also have a staging or QA deployment reachable by URL, secure it too, with its own key and its own origin. It’s tempting to leave a staging key unsecured since it’s “not real”, but it can still leak and get compromised.

Keep the keys for staging and production separate. Using a single key allowed for both URLs technically works, but it removes the isolation that keeping them separate is meant to give you, such as targeted analytics and easier key rotation.

Load the keys for staging and production from environment variables rather than hardcoding them.

Mobile or desktop app

For native applications, secure the key with Allowed User-Agent header: Enter a substring unique to your app’s User-Agent. Only requests carrying a matching User-Agent are processed.

Example: Substring coolest-mobile-map-app will work with User-Agent headers such as coolest-mobile-map-app-0.5, coolest-mobile-map-app-1.1 etc. but it will also work with my-friend's-coolest-mobile-map-app.

Backend-only usage

If your key never reaches a browser or an app your users install (for example, a server calling MapTiler API on their behalf), you don’t need to secure it, as the frontend rules don’t meaningfully apply to server-to-server calls.

We still recommend creating a dedicated key for this use, so you can track it separately.

Backend-mediated auth (advanced)

If you don’t want to expose an API key to the client at all, you can use a service token instead. Note that there’s some setup work involved, and you must keep all API calls strictly on your backend.

Best practices

• Use a separate key per map, so you can track each map’s traffic in analytics.

• Use a separate key per application and platform. Combining an allowed origin with User-Agent on the same key applies strict AND logic (meaning both must match), so mixing rules for different platforms on one key usually blocks legitimate requests. A separate key per platform avoids this, and lets you replace a key without affecting others.

• Rotate keys periodically. How often depends on your needs and risk tolerance, there’s no universally correct interval. A typical setup is 2–3 months. When you rotate, keep the old key active for a short overlap window while you switch your traffic to the new one, then revoke it. You can automate rotation using the API keys Service API.

If your key is compromised

The typical effect of a compromised key is unusually high traffic. Each pricing plan, including Free, has a specific API quota and the traffic on all your API keys counts towards it.

The chance of misuse is much higher if the key isn’t secured, but even secured keys can get compromised. We recommend that you regularly check analytics to see if there are any unexpected spikes. If you follow the best practices and create a separate key for each map or application, it will be easy to tell exactly which integration is affected. We also watch for major spikes and may reach out, but don’t rely on that alone.

What to do with a compromised key:

1. Go to the API keys page.
2. Create a new key, secure it, and replace the compromised key with the new one in your app’s code.
3. Revoke the old key to instantly block the traffic.

If the compromised key is embedded somewhere you don’t control and can’t rotate on your own (for example, deployed at your customer’s site), there’s no self-service fix today. Please contact our Support for help.