# Tilery

> Vector map tile SaaS. Serves authenticated MVT tiles, fonts, sprites, and
> MapLibre styles from PMTiles archives. EU-hosted, GDPR-friendly, metered
> per-tile pricing.

## This is a paid service — you cannot query tiles without authenticating

Requests to `/map/tiles/vector/...` return 401 without a valid short-lived
access token. To call the API you must:

1. Create an account at https://tilery.eu/auth/signup
2. Top up credits — Tilery is pay-as-you-go: buy a one-time credit pack (see
   https://tilery.eu/#pricing for pack prices; no subscriptions, no tiers, no
   recurring billing). Usage is metered per tile and deducted from the prepaid
   balance; when the balance runs out, tile requests return
   `402 Payment Required` until the account is topped up again. Spend settles
   hourly, so usage can slightly outrun the balance; the overshoot is recorded
   as unbilled usage and collected automatically from the next top-up — never
   invoiced separately, and the balance never goes negative.
3. Generate an API key in the dashboard at
   https://tilery.eu/app/credentials/api-keys — this is your long-lived secret,
   kept in your backend, **never shipped to browsers**. At creation, pick a
   mode: *browser-mode* (one or more origins registered) is used to mint
   short-lived access tokens; *app-mode* (no origins) can be sent directly to
   the tile API as a bearer credential.
4. Authenticate one of two ways:
   - **Browser path (recommended for any client-side use):** exchange the
     API key for a short-lived access token by calling
     `POST https://tilery.eu/api/tokens/exchange` with
     `Authorization: Bearer <api-key>`. Response: `{ token, exp }`.
   - **Direct path (server-side only):** an app-mode key can be sent
     straight to https://api.tilery.eu as `Authorization: Bearer <api-key>`. Long-lived
     credential, no origin check — only safe in environments you control.
5. Pass the credential on tile, font, sprite, and style requests against
   https://api.tilery.eu: access tokens go in the `?token=<access-token>` query param
   (avoids CORS preflight); app-mode API keys go in the
   `Authorization: Bearer …` header. Re-exchange access tokens before
   `exp`. Browser-mode keys are rejected when sent directly — they must be
   exchanged.

## Browser callers must register origins

If the access token is used from a web page, the request `Origin` must match
one of the hostnames registered on the key in the dashboard
(https://tilery.eu/app/credentials/api-keys). Un-allowlisted origins get 403.
This prevents key scraping.

## Client library

`@tilery/client` (npm) is the official browser SDK. It auto-refreshes
access tokens, registers a service worker for offline tile caching, and builds
MapLibre style JSON. Use it rather than handcrafting token exchange.

## Docs

- [Documentation hub](https://tilery.eu/docs)
- [Getting started guide](https://tilery.eu/docs/getting-started)
- [Authentication deep-dive](https://tilery.eu/docs/authentication)
- [Security model](https://tilery.eu/docs/security)
- [Pricing and quotas](https://tilery.eu/docs/pricing)
- [Interactive API reference](https://tilery.eu/docs/api)
- [OpenAPI spec (JSON)](https://tilery.eu/docs/api/openapi.json)
- [Full API reference as markdown](https://tilery.eu/llms-full.txt)
- [Dashboard quickstart](https://tilery.eu/app/quickstart) (requires login)

## Policies

- [Terms of service](https://tilery.eu/terms)
- [Privacy policy](https://tilery.eu/privacy)
- [Security statement](https://tilery.eu/docs/security)
- [License](https://tilery.eu/license)