API Keys & Security
Every request against the gateway is authenticated by an API key. This page covers how the key is passed, what it can and can't do, and how to read the errors it produces when something is wrong.
How Keys Are Passed
The key is sent as a token query parameter — not a header, not a bearer token.
curl "https://gateway.mapmetrics-atlas.net/v2/autocomplete/?q=Nieuwezijds%20Voorburgwal%20147&country=nl&token=YOUR_API_KEY"fetch(`https://gateway.mapmetrics-atlas.net/v2/forward-geocode/?q=Nieuwezijds%20Voorburgwal%20147&country=nl&format=pelias&token=YOUR_API_KEY`);No Authorization: Bearer header
There is no header-based auth on this gateway. Authorization: Bearer YOUR_API_KEY is silently ignored — the key must be the token query parameter on the request URL.
Scopes
A key carries one or more scopes, and each endpoint requires a specific scope to authorize it:
| Scope | Endpoints |
|---|---|
autocomplete | /v2/autocomplete/, /v2/retrieve/, /v2/retrieve-batch/ |
geocode | /v2/forward-geocode/, /v2/reverse-geocode/ |
osm-geocode | /osm-geocode/, /osm-reverse/ (free OpenStreetMap tier) |
Scopes are additive: one key can carry autocomplete, geocode and osm-geocode at the same time, and a key holding all three can call both the paid v2 endpoints and the free OpenStreetMap tier. There is no separate "OSM key" — it is a scope, not a kind of key.
Because scopes are checked per endpoint, a key that works fine against /v2/autocomplete/ can still 401 against /osm-geocode/ if it was not issued the osm-geocode scope. That is expected scoping behavior, not a broken key — see scope_not_allowed below.
Note that holding the scope does not route requests for you: the two tiers are different endpoints, so switching to the free tier is an explicit choice at call time (in the SDKs, a tier option on the client).
Origin Restrictions — and Their Hard Limit
A key can be restricted to a list of allowed website origins. When a key has an origin restriction set, the request's Origin header must match one of the listed domains.
This is a browser-only control
Origin restriction only works because browsers set the Origin header themselves and don't let page JavaScript forge it. Native apps, backend servers, curl, and Postman send no Origin header at all — there's nothing there to check.
An origin-restricted key used from any non-browser client returns 403 origin_required. This is by design, not a misconfiguration on your end — origin restriction fundamentally cannot apply to a client that sends no origin. Do not use origin-restricted keys outside the browser.
The two origin-related errors look similar but have opposite fixes:
403 origin_required— noOriginheader was present on the request at all. This means the client is not a browser (native app, server, curl, Postman). Adding the domain to the key's allow-list will not help — the fix is to use a key without an origin restriction for that client.403 origin_not_allowed— anOriginheader was present (it's a browser request), but its domain isn't in the key's allow-list. This one is fixable: add the domain to the key's allowed origins.
Telling someone with origin_required to "just add your origin" sends them in circles — their client has no origin to add. Check which of the two errors you're looking at before suggesting a fix.
Understanding Auth Errors
| Error | Meaning |
|---|---|
401 Token required | No token parameter was present on the request. |
401 token_not_found | The key is not provisioned. A correctly-formed token still fails if it was never issued — regenerating the token string does not fix this; the key has to actually exist server-side. |
401 token_inactive | The key exists but has been deactivated. |
401 scope_not_allowed | The key is valid but lacks the scope this endpoint requires. |
403 origin_required | No Origin header on the request — see above. |
403 origin_not_allowed | An Origin header was present but not on the key's allow-list — see above. |
Key Exposure — Be Honest About It
An API key embedded in browser JavaScript is visible to anyone who opens DevTools. A key embedded in a mobile app is recoverable from the compiled binary by anyone willing to decompile it. Neither environment can actually keep a key secret.
Origin restriction is a best-effort mitigation for browser keys, not a secret-keeping mechanism — it stops casual reuse of a key copied off your site, but it is not cryptographic protection, and it does nothing at all for a key shipped inside an app.
Recommendation:
- Scope browser-exposed keys to only what the page actually calls (e.g.
autocompleteonly, if that's all the page uses). - Keep higher-value scopes —
geocode,osm-geocode— on server-side keys that never reach the client.
Usage Limits
The OSM free tier is 10,000 requests per key per day, plus a global monthly cap across all free-tier keys.