API keys and access

Send an application key #

Prerequisites: a key issued for your application/environment. Send it as X-API-Key on API and download requests. For renderers that cannot set headers, use ?key=. The style endpoint propagates a query key into tile, font and sprite URLs. A header key authenticates the style fetch but is not automatically inserted into its resource URLs.

const response = await fetch('https://maps.example/search?q=Lahug', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const data = await response.json();
if (!response.ok) throw new Error(data.error);
console.log(data.features);

The viewer page, shared JavaScript modules, vendor assets, npm tarballs and maps /healthz are public. Map data and services require a key even when their JavaScript libraries are public.

Expiry, rotation and suspension #

• Secrets are shown once when staff issue or rotate a key. Store them before closing that dialog.
• Use separate application records for development and production. Grant only the scopes your integration needs.
• Immediate rotation revokes the old key. Overlap rotation keeps it usable until the selected deadline, subject to the original expiry. Expired/revoked keys cannot be rotated.
• Revoking a key, suspending its application or suspending its organization blocks access. Authorization changes take effect within about five seconds.
• An issued browser or native app key is visible to its user. Do not treat a distributed client key as a secret boundary.

Expected result after rotation: new requests succeed with the replacement key; the previous key fails after retirement. Test a release request and every enabled service before retiring the old key.

Use an application gateway #

For a public application, authenticate users at your own gateway and attach the application key server-side. Proxy /maps/, /search, /route and /depth. Preserve Range and response metadata, do not compress PMTiles, and do not let clients spoof trusted identity headers. Configure the browser with the gateway root and no API key.

import { configure, releaseInfo } from '@sw-maps/core/services';
configure({ baseUrl: 'https://app.example/', apiKey: null });
console.log((await releaseInfo()).release);

Your gateway must enforce its own user authorization. Forward X-Forwarded-Proto, X-Forwarded-Host, and, when applicable, X-Forwarded-Prefix so returned style URLs use the browser-visible origin/path. Or request a style with an explicit URL-encoded base pointing to the public map-data root. See Styles and overlays.

Access errors and portal login #

Never paste production keys into shared links, documentation, screenshots, source control or support tickets. Examples here contain placeholders only. Portal cookies and Bearer session JWTs do not authorize maps requests; application keys do not authorize management APIs.