--- title: "API key | Guides" description: "How to get an API key and secure it properly." --- > For AI agents: a documentation index is available at [/llms.txt](https://docs-beta-4y5.pages.dev/llms.txt). Markdown versions of all pages are available by appending .md to any URL. # 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: ```text 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](https://cloud.maptiler.com/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. Tip To see how many API keys you can create, go to [Account > Settings](https://cloud.maptiler.com/account/settings), section **Keys**. If you need more, [contact us](https://www.maptiler.com/#contact). ## 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](#compromised-key). 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. Note If you’re a developer testing with a local web server (address starting with `http://localhost`), you don’t need to leave the key unsecured – see [Local testing](#local-testing). 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:` or `http://127.0.0.1:` 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`. Warning Allowing localhost isn’t real security – it matches any machine, including an attacker’s. Never leave this rule on a key used in production, and make sure to secure production keys with your real domain only. If you’re opening the HTML file directly (`file://`) rather than running a local server, see [Simple map embedding](#simple-embed). #### 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. Note The match is case-sensitive and only needs to be a substring, so keep it unique to your app to avoid accidentally matching someone else’s User-Agent. **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](#security-off). 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](https://docs-beta-4y5.pages.dev/guides/developer/credentials/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](#secure-key). 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](#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](https://cloud.maptiler.com/account/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](https://docs-beta-4y5.pages.dev/cloud/admin-api/api-keys/). ## 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](https://cloud.maptiler.com/account/settings) and the traffic on all your API keys counts towards it. Warning On a paid plan, rogue traffic on a stolen key can lead to high extra costs that you will be billed for. On a free plan, your maps might get suspended for the rest of the billing period. 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](https://cloud.maptiler.com/account/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](https://cloud.maptiler.com/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](https://docs-beta-4y5.pages.dev/support/requests/) for help.