TomTom Authentication: API Key Setup & Security (2026)

Authentication overview

TomTom APIs secure access to their mapping and location services primarily through the use of API keys. This mechanism provides a simple yet effective way to identify and authorize applications consuming TomTom's various APIs, including Maps, Traffic, Routing, Geocoding, and Search APIs. An API key acts as a unique identifier for your application and is required for nearly all requests made to the TomTom API endpoints.

When an application sends a request to a TomTom API, the API key is included as a query parameter in the request URL. TomTom's servers validate this key against registered keys in their system. If the key is valid and authorized for the requested service, the API processes the request and returns the appropriate data. This process ensures that only authenticated applications can access TomTom's geospatial data and services, helping to manage usage and enforce rate limits tied to specific developer accounts.

The developer experience is streamlined with comprehensive SDKs for web, Android, and iOS, which facilitate the integration of API keys into various application environments. TomTom's documentation provides detailed guidance on how to implement authentication across different platforms, ensuring developers can quickly get their applications up and running with secure access to location data.

Supported authentication methods

TomTom primarily supports API key authentication for accessing its suite of APIs. While other authentication methods like OAuth 2.0 are common in enterprise environments for user authorization, TomTom focuses on API keys for application-level access to its developer services. This choice simplifies the integration process for developers who need to access geospatial data and services directly from their applications.

An API key is a unique token that you obtain from the TomTom Developer Portal. It is used to authenticate your application when making calls to TomTom's various APIs. The key identifies your project and links API requests to your usage account, which is crucial for billing and usage monitoring. Each API key can be configured with specific restrictions to enhance security, such as limiting its use to particular HTTP referrers or IP addresses.

For scenarios requiring user authentication or more granular access control beyond application identification, developers typically implement their own user authentication systems within their applications and then use the TomTom API key for backend service calls. This separation of concerns allows developers to manage user identities independently while relying on TomTom's API key for secure service access.

The following table summarizes the primary authentication method supported by TomTom:

Getting your credentials

To begin using TomTom APIs, you must first obtain an API key from the TomTom Developer Portal. This process is straightforward and typically involves creating an account and then generating a new key associated with your project. Here's a step-by-step guide:

1. Create a TomTom Developer Account: If you don't already have one, navigate to the TomTom Developer Portal and sign up for a new account. This account will be linked to your API usage and billing.
2. Access the Dashboard: Once logged in, go to your developer dashboard. This is usually where you manage your projects and API keys.
3. Create a New Project: You might need to create a new project before generating an API key. A project helps organize your API keys and usage statistics.
4. Generate an API Key: Within your project, look for an option to generate a new API key. TomTom provides clear instructions on this process, often with a dedicated button or section for key management.
5. Configure Key Restrictions (Optional but Recommended): After generating your key, you have the option to add restrictions. This is a critical security step. You can restrict the key's usage to specific HTTP referrers (for web applications) or IP addresses (for server-side applications). For example, if you are developing a web application hosted at example.com, you would add *.example.com/* as an HTTP referrer restriction. For more details on this, refer to the TomTom API key management documentation.
6. Store Your Key Securely: Once generated, your API key will be displayed. Copy this key and store it securely. Treat your API key like a password; do not embed it directly into publicly accessible client-side code without proper restrictions.

TomTom's free tier allows for 2,500 transactions per day, which is sufficient for initial development and testing, and is accessible using the API key obtained through this process. For more details on pricing and usage, consult the TomTom pricing page.

Authenticated request example

After obtaining your API key, you can include it in your API requests. The key is typically passed as a query parameter named key in the request URL. Below are examples demonstrating how to make an authenticated request using different methods.

HTTP GET Request (General)

This is a basic example of an HTTP GET request to a TomTom API endpoint, such as the Geocoding API, including the API key:

GET https://api.tomtom.com/search/2/geocode/London.json?key=YOUR_API_KEY&limit=1 HTTP/1.1
Host: api.tomtom.com

Replace YOUR_API_KEY with the actual key you generated from the TomTom Developer Portal.

JavaScript (Web SDK)

When using the TomTom Web SDK, the API key is usually set during the initialization of the map or other services. This example shows how to initialize a map with your API key:

import tt from '@tomtom-international/web-sdk-maps';

const map = tt.map({
  key: 'YOUR_API_KEY',
  container: 'map-div',
  center: [-0.112869, 51.5041],
  zoom: 13,
});

map.addControl(new tt.NavigationControl());

For detailed guidance on integrating the Web SDK, refer to the TomTom Web SDK overview.

Python (Server-Side)

For server-side applications, you can use a library like requests to make authenticated calls. It's best practice to load your API key from environment variables:

import os
import requests

api_key = os.environ.get('TOMTOM_API_KEY')
if not api_key:
    raise ValueError("TOMTOM_API_KEY environment variable not set.")

query = "Eiffel Tower"
url = f"https://api.tomtom.com/search/2/search/{query}.json?key={api_key}"

try:
    response = requests.get(url)
    response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

Ensure that TOMTOM_API_KEY is set in your environment before running this script.

Security best practices

Securing your API keys is crucial to prevent unauthorized access to your TomTom account and services, which could lead to unexpected usage charges or service disruptions. Adhering to these best practices will help protect your applications and data:

1. Use Key Restrictions: Always apply HTTP referrer restrictions for web applications and IP address restrictions for server-side applications. This ensures that even if your API key is exposed, it can only be used from authorized domains or servers. TomTom's developer portal provides the interface to set these restrictions.
2. Never Embed Keys Directly in Client-Side Code Without Restrictions: While TomTom's Web SDK allows direct embedding, it is imperative that strong referrer restrictions are in place. Without them, embedding an API key directly in client-side JavaScript makes it easily accessible to anyone inspecting your webpage's source code. For browser-based applications, ensure referrer restrictions are correctly configured to match your domain(s).
3. Store Keys Securely in Server-Side Applications: For backend services, never hardcode API keys directly into your source code. Instead, use environment variables, dedicated configuration files that are not committed to version control, or a secure secrets management service. This practice aligns with the principle of least privilege and prevents keys from being exposed in code repositories.
4. Rotate API Keys Periodically: While TomTom API keys do not expire automatically, it's a good security practice to rotate them periodically. This involves generating a new key, updating your applications to use the new key, and then revoking the old key. This minimizes the impact of a compromised key.
5. Monitor API Usage: Regularly check your API usage statistics in the TomTom Developer Portal. Unusual spikes in usage could indicate a compromised API key or malicious activity. Set up alerts if available to notify you of abnormal usage patterns.
6. Use Separate Keys for Different Environments and Applications: Avoid using the same API key for development, staging, and production environments, or across different applications. Using separate keys allows you to revoke a compromised key without affecting other environments or applications. It also simplifies usage tracking and debugging.
7. Implement a Proxy for Client-Side Access (Advanced): For enhanced security in client-side applications, consider routing API requests through your own backend proxy server. Your client-side application requests data from your proxy, which then makes the authenticated call to TomTom using your securely stored API key. This completely hides your API key from the client-side, making it impossible for users to extract.

By diligently following these security practices, you can significantly reduce the risk of unauthorized access and ensure the integrity of your applications using TomTom's location services.