Authentication and keys

Every /v1 request carries the X-Api-Key header. On the tile server the key is optional (Tiles and styles).

curl -sS "https://api.updraftmaps.com/v1/sites?bbox=28.5,36.0,30.0,37.2&kind=takeoff" \
  -H "X-Api-Key: $UPDRAFT_API_KEY"

Getting a key

Keys are issued, revoked and given their quota by an Updraft administrator; there is no self-service sign-up yet. When you ask, tell us:

the endpoints you will use (scopes, below);
the origin of your web site or app (for tiles from the browser, e.g. https://example.com);
roughly how many requests you expect.

A key is a 47-character string starting with upd_ and is shown to you once; Updraft keeps only a hash of it. If it is lost, a new one is issued and the old one revoked.

Scopes

A key may carry several scopes. Do not ask for more than you need; keep reading and writing keys apart.

Scope	Endpoints
`tiles`	Keyed tile path, GET /v1/packs/{region}
`sites:read`	GET /v1/sites, GET /v1/regions, GET /v1/regions/{region}/profile
`flights:write`	POST /v1/flights (IGC upload, server to server)
`consents:write`	POST /v1/consents/withdrawals, POST /v1/consents/grants
`flights:share`	POST /v1/flights/{flight_id}/shares, DELETE /v1/flights/{flight_id}/shares
`replay:read`	GET /v1/replay/{public_id} (the Updraft Atlas server only)

GET /v1/health and the time-limited download addresses of region packs need no key.

Authentication errors

HTTP	`code`	What to do
401	`auth_missing`	Add the `X-Api-Key` header
401	`auth_invalid`	Unknown key: check its spelling and your environment
401	`auth_revoked`	The key was revoked: ask for a new one
403	`auth_scope`	The key lacks this endpoint's scope: ask for the scope

A 401 carries the WWW-Authenticate: ApiKey header. Repeating the same request does not help. Authentication is checked before file and field validation; 401 and 403 are not counted. Body format: Errors.

Browser and mobile

Server keys (sites:read, flights:write …) live only on your server, in an environment variable or a secret manager; never in a browser, a mobile app, a repository or a log.
Browsers and mobile apps use a separate key with the tiles scope only. Such a key can be extracted from the client; if it leaks only tiles can be read, an administrator revokes it and gives you a new one. A revocation takes effect on the tile server within 30 seconds.
Send the key in a header (MapLibre transformRequest, flutter_map TileLayer headers, maplibre_gl setCustomHeaders). The ?key= query is accepted too, but it ends up in proxy and CDN logs.

Client packages

Two thin packages handle the header, the addresses and the error body for you; their version equals the API version:

Package	Install	Content
`@updraft/maps` (TypeScript/JavaScript)	`npm install @updraft/maps`	`UpdraftClient` (every `/v1` endpoint, types generated from OpenAPI), `UpdraftApiError` (`code`, `detail`, `retryAfter`, `retryable`), tile and style addresses; `@updraft/maps/maplibre` MapLibre GL JS helpers
`updraft_maps` (Dart/Flutter)	`flutter pub add updraft_maps`	`UpdraftClient`, `UpdraftApiException`, tile addresses; `flutter_map.dart` and `maplibre_gl.dart` helpers

import { UpdraftApiError, UpdraftClient } from '@updraft/maps';

const client = new UpdraftClient({ apiKey: process.env.UPDRAFT_API_KEY }); // server only
try {
  const page = await client.sites({ bbox: '28.5,36.0,30.0,37.2', kind: 'takeoff' });
} catch (error) {
  if (error instanceof UpdraftApiError && error.code === 'auth_scope') {
    // the key needs the sites:read scope
  }
}

Route suggestions (GET /v1/routes) are for pre-flight planning only: whenever you show the options, also when there are none, show the answer's fixed notice too (preflightNotice(answer, 'en')).