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#1.0/0.00000/0.00000

Replace YOUR_MAPTILER_API_KEY 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. In your MapTiler account, go to Credentials.
2. Click New API key and give the key a name. Or if you want to use an existing key, find it in the list.
3. In the key’s menu, select Secure key. On the Web or Mobile tab, add the rules that fit your use case (see below).
4. In the key’s menu, select Copy key to have it ready.

Changes to a key’s security take up to 5 minutes to apply.

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 on the Web tab with the website 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 on the Web tab with the website origins your app runs on:

• Add each domain your app runs on, for example mydomain.com.
• 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 origin. It’s tempting to leave a staging key unsecured since it’s “not real”, but it can still leak and get compromised.

If your plan allows more API keys, 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 on the Mobile tab: enter a substring unique to your app’s User-Agent header. 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. To stop the warnings about the unsecured key, turn off Security.

If your plan allows more API keys, create 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.

Keys that don’t need security

An unsecured key is highlighted in red in your account, and you get prompts to secure it. If you have a good reason to leave a key unsecured, for example because it’s only used from your backend, you can turn off these warnings: open the key’s Settings and switch off Security. You won’t get any prompts or alerts about suspicious activity for that key anymore.

Security rules reference

All the values you can enter when you secure a key, in one place. To find out which ones fit your app, see Secure your key by use case.

If a key has both website origins and a User-Agent, a request must match both.

Website origins

Enter these on the Web tab, without protocol (https://) and port.

Value	Example	What it allows
Domain	mydomain.com	Requests from that domain.
Wildcard	*.mydomain.com	Requests from its subdomains.
Local server	localhost or 127.0.0.1	Requests from your local dev server. For testing only, see Local testing.
Question mark	?	Requests with no Origin header. Avoid without a specific reason.

User-Agent

Enter this on the Mobile tab: a substring of your app’s User-Agent header.

• The match is case-sensitive.
• A substring is enough: coolest-mobile-map-app matches coolest-mobile-map-app-1.1.
• Keep it unique to your app, so it doesn’t match other apps’ User-Agents.

Best practices

Most of these need more than one API key. How many keys you can create depends on your plan.

• 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 website origins with a 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 once your application is in professional or commercial use, which needs a paid plan. 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 delete 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 Credentials.
2. Create a new key, secure it, and replace the compromised key with the new one in your app’s code. If your plan doesn’t allow another key, delete the compromised key first.
3. Delete the old key to block its traffic. The key’s historical traffic stays available in analytics.

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.