Where your API key runs

Where the SDK runs decides how much care your API key needs:

• The Services bundle runs in Node.js, so search, geocoding, routing and traffic calls can run on a server, in a cron job or a script, with no front-end at all.
• The Map bundle renders in the browser, so any key it uses travels to the browser with it.

TomTom's API key management best practices cover keys in general: scoping, segregation, rotation and monitoring. What follows is specific to the SDK, and to a key that has to sit in a page.

Which situation you are in

Server-side apps (Node.js)

A nightly geocoding job, a CLI script, an API of your own that calls routing, a queue worker, tests and CI: the key stays inside your infrastructure, so the proxying and hardening guides are not for you.

Read the key from the environment rather than from source:

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';

TomTomConfig.instance.put({
    apiKey: process.env.TOMTOM_API_KEY,
});

Particular to the SDK:

• Redact both forms of the key in your logs. Some services send it as a TomTom-Api-Key header, others as a key= query parameter (which is which).
• The SDK already retries and validates. It retries 429 responses with backoff bounded by retry.timeoutMs, and validates requests by default, so a malformed one is rejected before it becomes a billable call. A retry loop of your own multiplies the attempts.

On a server, the realistic failure is your own code, since every call is billed: count a batch job's input before you start it, cap concurrency, and cache what you have already resolved.

If your Node.js code serves a front-end, what you return to the browser must not contain the key: not in a config endpoint, not in server-rendered HTML, not in a serialized state blob.

Server-side rendering blurs the line. A framework that runs the same component on the server and the client will inline process.env.TOMTOM_API_KEY into the browser bundle, and variables with a public prefix (NEXT_PUBLIC_, VITE_) are client-visible by design. Check what your build actually ships before assuming a key is server-only.

Browser apps

A page that shows a map needs a key in the browser. For most applications that is fine.

It deserves a second look when your application is public and anonymous: anyone who opens the page can read the key and use it from their own application, on your bill. Behind a login you know who your users are; self-service signup counts as public.

The test: if someone started using your key from their own application tomorrow, would you find out? If not, take these measures. They are settings on the key in the dashboard, nothing you have to build:

• A domain whitelist, so a copy stops working from anyone else's page. The cheapest measure there is, though it does not stop a non-browser client.
• Only the products you use, so a copy buys less than full access.
• One key per application and environment, so a compromise is contained and you can revoke without a coordinated release.
• Query limits, which turn an open-ended bill into a capped one.
• Per-key analytics, because how quickly you notice decides how big the surprise gets.
• Rotation on a schedule. A rotated key stays valid for up to 48 hours, which is your window to ship a new build and let caches drain.

The best practices detail each. Together they cap the damage and make a leak visible quickly, which for many applications is the whole answer.

When a proxy is worth it

Only a server, yours or a proxy, takes the key off the page. Everything above leaves the key public and limits what it is worth, which is often the right trade.

Two cheaper steps come first:

• Move service calls into a backend of your own. That takes the key off those calls, though the browser still fetches the map's tiles.
• Set the key's restrictions above, an afternoon's work with no infrastructure.

Move to a proxy when a stolen key would be a bill you would notice, when your application is public and anonymous at meaningful volume, or when you rotate keys because of abuse rather than policy. An unguarded proxy is your key with extra steps, so proxying your API calls and hardening your proxy are one job.

Next steps

• Proxying your API calls - The SDK's built-in proxy mode, and what the proxy itself needs to do.
• Hardening your proxy - The checks that keep the proxy from becoming a public key of its own.
• Global configuration - Where apiKey and commonBaseURL are set, including in Node.js.
• API key management best practices - TomTom's platform guidance on restrictions, rotation, segregation and monitoring.
• Securing your agent - If you build with the Agent Toolkit, the model provider key needs the same treatment, plus limits of its own.