API Keys: Best Practices

We rely on API Key to identify applications using our TomTom public APIs. API Keys are used to provide access to our services and monetize them.

We follow OWASP best practices when it comes to API Key management. As it is the key that will authenticate your application against our services, we advice you to follow common best practices regarding API Keys.

Depending on how your API key is used after it has been created, you may face different constraints for securing it.

For example, replacing a Key in a mobile application is more difficult than in a backend system or web application. Changing a key will require good planning and fast execution if you want to keep your application safe.

In this document, we list a set of practices and recommendations for you to properly manage your API keys and avoid fraudulent usages that may result in data loose or receiving excessive bills.

Limit the scope of your API Key

You should restrict you API Key to reduce the attack surface in case of leaks. TomTom API Keys scope can be restricted per domain and per product.

Domain Whitelisting: if your API key is used in a web page (for example, with the web tomtom SDK), you should define a domain whitelist for your key.
Product Restriction: you can restrict the range of products accessible using your Key.

Note: you should use different keys per applications and use cases. If you have an Android and IOS application, they should each have their own key. If you have a system using a set of product and another system using another set of product, they should also have their own keys.

Set a Domain Whitelist for your API Key

Note: We have a blog article explaining how to add whitelisted domains

Go to your Key Management Page
Select an API Key to edit
Set a comma separated list of domains to whitelist (wildcard * can be used)
Click on Save Key at the bottom

This feature relies on Cross-Origin Resource Sharing CORS header to limit the domain that can access our APIs using your API Key.

Set a product restriction for your API Key

Go to your Key Management Page
Select an API Key to edit
Select the products you want to enable for your API Key
Click on Save Key at the bottom

Delete Unused API Keys

Having unused API keys wandering around can be a risk. After checking that your API Key is not used in any of your environment anymore, you should delete it. To help you verify if an API Key is still used, you can use the Key Activity Dashboard.

Go to your Key Management Page

Select an API Key to delete

Regenerate your API Key

If you suspect that you API Key was leaked and is being fraudulently used, you may want to rotate it. TomTom offers a Key rotation mechanism.

Key rotation is a feature that allows you to regenerate your API keys via the developer dashboard. Once the key rotation is triggered for a certain API key you will be immediately provided with a new key. However, old key will continue to work for the specified amount of time (up to 48 hours) to allow you to perform necessary code changes.

Please note that key rotation cannot be undone. Once the old key expires, it is not possible to reinstantiate it.

Monitor your API usage

To avoid bad surprises at the end of a billing cycle. You should monitor the usage of your API key using Developer Portal Activity Dashboard to detect abnormal consumption

Use one API Key per application

Use multiple API Key with each API Key assigned to a specific application. It will make it easier for you to rotate the key if it used by one application instead of multiple.

You should use a different API key between WRITE and READ applications with higher security considerations for securing your WRITE API Key

Apply Rate Limiting

We enforce a default rate limit on API Keys. You may also want to refine it and make it closer to your real consumption and avoid excessive billing.

You can contact our sales if you want to opt-in for custom rate limiting.

Protect your API Key in backend applications

You should follow OWASP secret management best practices for securely handling your API key in your software development lifecycle.

Protect your API Key in frontend applications

Use a proxy server to interact with TomTom API. The proxy server can enforce a different Authentication scheme and use the API key to forward authorized requests to TomTom APIs.

If your TomTom APIs are called from a mobile application. Encrypt or obfuscate the API key in your application. You may want to implement a system to rotate the key in the application (through a remote config mechanism) without requiring a full update.

What do we do at TomTom?

When receiving your API Key, we follow best practices to ensure that it does not leak from our system.

We limit the API Key propagation

We limit the propagation of the API key. Only the API Gateway and its security components see the API key. After verification, we remove it from the subsequent requests in our systems.

We do not log your API Key

We consider the API Key as a credential information and treat it as such. It means that we do not log the API Key in our systems.

We restrict the access to API Key information

API Key information are securely stored in the API Gateway component and we enforce strict restriction for accessing those information.