Getting started

1. Create an account and top up credits

Tilery rejects unauthenticated tile requests, so the first step is always an account with a topped-up credit balance. Billing is pay-as-you-go: buy a one-time credit pack, and every tile served comes out of your balance — no subscription, no recurring billing. When the balance runs out, requests return 402 until you top up again (any usage that slips past the stop is collected from your next top-up) — see Pricing & quotas for the mechanics.

2. Generate an API key

Open API keys in your dashboard and create one. The full key is displayed exactly once — copy it immediately. API keys are long-lived secrets — treat them like a password.

At creation you pick the key's mode:

• Browser-mode (one or more origins registered): kept on your backend, used only to mint short-lived access tokens in step 3 — never shipped to a browser or mobile app itself. Origin-locked, recommended for any client-side integration on the public web.
• App-mode (no origins): can be sent straight to the tile API as a Bearer credential, skipping the exchange step. Convenient for trusted backends, CI, scripts, and mobile/native apps where you accept that the key ships inside the binary. Token exchange via your own server is more secure (15-minute blast radius, easy revocation), so use app-mode only when the operational simplicity is worth the longer leak window. See the security model for the tradeoff in full.

3. Exchange the API key for an access token (browser path)

For browser-mode keys (and any time you want a 15-minute blast radius), your backend exchanges the key for a short-lived access token via POST /api/tokens/exchange. Re-exchange before the exp timestamp.

# Exchange your API key for a short-lived access token (max 15 min TTL)
curl -X POST https://api.tilery.eu/api/tokens/exchange \
  -H "Authorization: Bearer $TILERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 900}'
# => { "token": "eyJ...", "exp": 1700000000 }

// Backend (Node) — exchange once, refresh before exp
const res = await fetch("https://api.tilery.eu/api/tokens/exchange", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TILERY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ ttl: 900 }),
});
const { token, exp } = await res.json();
return { token, exp };

App-mode keys can skip this step — see step 4 for the direct path.

4. Fetch your first tile

On the access-token path, pass the token as a ?token= query param on every tile, font, sprite, or style request. The query form avoids a CORS preflight that an Authorization header would trigger — the header is still accepted if you need it server-side.

On the direct path, send your app-mode API key as Authorization: Bearer … on the same tile URLs. Browser-mode keys are rejected here and must be exchanged first.

# Fetch a tile — the access token goes in the ?token= query param
# (Authorization: Bearer is also accepted as a fallback)
curl "https://api.tilery.eu/map/tiles/vector/0/0/0?token=$TILERY_ACCESS_TOKEN" \
  -o tile.pbf

# App-mode keys (no origins registered) can be used directly,
# skipping the exchange step. Long-lived credential — backend only.
curl -H "Authorization: Bearer $TILERY_API_KEY" \
  https://api.tilery.eu/map/tiles/vector/0/0/0 \
  -o tile.pbf

5. Integrate with the client SDK

In practice you'll use @tilery/client in the browser. It calls your backend's token endpoint, refreshes before expiry, registers a service worker for offline caching, and builds a MapLibre style. Refresh keeps the client's token fresh — the map needs client.attachToMap(map) (or a transformRequest) so tile requests pick up each new token; without it, tiles 401 once the first token expires.

import { TileryClient } from "@tilery/client";
import maplibregl from "maplibre-gl";

// getToken is called automatically; point it at your backend's exchange route
const client = new TileryClient({
  getToken: async () => {
    const res = await fetch("/api/tile-token", { credentials: "include" });
    if (!res.ok) throw new Error("Failed to get access token");
    return res.json();
  },
});

await client.registerServiceWorker();

const map = new maplibregl.Map({
  container: "map",
  style: await client.getMapStyle({ flavor: "dark" }),
  center: [10.75, 59.91],
  zoom: 12,
});

// Tokens live max 15 min — this keeps tile requests on the current
// token across refreshes (the style bakes the initial token in once)
client.attachToMap(map);

6. Lock down browser origins

If the access token will be used from a web page, register the exact hostname (and port, if it's non-default) on the key under API Keys. Un-allowlisted origins get a 403 — this is what stops someone from scraping a token out of your site and reusing it on theirs.