Authentication

Authentication is a way of proving someone’s identity. In case of MapTiler’s online maps and services, every request must be authenticated, so that we know it’s you or your map users making the request.

For example, if you embed a MapTiler map on your website, then every time someone visits that page, their browser sends a request to MapTiler servers to get the map. This request must be authenticated, otherwise the map won’t show up on the page.

Which authentication method to use?

MapTiler offers two authentication methods. Which one is best depends on your needs:

• An API key is a simple and easy-to-use authentication for client-side use such as web apps. If you want to use a map on your website or build a mobile application using MapTiler’s online maps and API services, you’ll typically want to use an API key. 👉 Using an API key

• A token provides advanced and highly secure authentication for backend use. You’ll need it in these scenarios:

  • You’re planning to use the admin API services. These API calls make it possible to not only read, but also modify and delete your cloud resources, so the highest security is in order.
  • You’re building a map application, but you don’t want to use an API key. It is possible to use a token for better security, but remember! The token itself must never get exposed, so if your app’s source code is public (for example on the web frontend), you’ll need to do some extra work to keep the token hidden in the backend. 👉 Using a token

API Key

An API key is a unique identifier that enables you to use all cloud API services such as maps, coordinates, location search, and more.

Example of an API request authenticated with an API key:

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

If you replace YOUR_MAPTILER_API_KEY_HERE with your actual key and paste the URL in your browser’s address bar, you’ll see the map.

Get an API key for testing

To work with your API keys, you need to be signed in to your MapTiler Cloud account. If you don’t have one yet, create it – it’s fast, easy, and free. Then follow these simple steps:

1. Go to page API keys.
2. Copy the Default key and use it to play around and test your maps. Never use it publicly!

Create a protected API key for production

The requests authenticated with an API key are visible to the world, which means that anyone can see and potentially steal your API key. The thief cannot change or break your maps, because the API calls are read-only, but their usage counts towards your API request quota and can lead to extra costs (if you’re on a paid plan) or unavailability of your maps.

To protect your API key from misuse, create a new key for each of your applications with a set origin (specific web domain or application allowed to use the key). Using a separate key per application makes it easy to replace the key if it does get compromised. You can even create a separate API key for each of your maps to better track its traffic in your cloud analytics.

To create a new key, protected from misuse, follow these steps:

1. Go to page API keys.
2. Click on New key.
3. Enter a short descriptive name for your key.
4. Select and fill in one of these methods to protect your key:
   1. Allowed HTTP origins restrict the API calls made with this key only to specific domains. This option is best if you’re going to use a MapTiler map on your website (specific domain).
   2. Allowed user-agent header restricts the API calls made with this key only to a specific application. Typically, you’ll want to use this option with your own custom mobile or desktop application, in which you can easily modify the User-Agent HTTP header and make it unique.
5. Click Create. Your new key appears on the API keys page, where you can find it anytime.
6. Copy the API key and use it. 👉 See an example of how to display an interactive map on your website using your API key.