API Authentication

The GeoLens REST API supports three authentication methods. Pick the one that matches your client:

• JWT Bearer tokens: short-lived, good for end-user apps and the web UI.
• API keys: long-lived, good for scripts, dashboards, and machine clients.
• OAuth/OIDC: admin-configured, good for SSO via Google, Microsoft, or generic OIDC providers.

Resolution order on every request: X-Api-Key header -> ?api_key= query parameter -> Authorization: Bearer <jwt> header -> anonymous. The first match wins.

Replace https://geolens.example.com with your GeoLens instance’s URL in every example below.

JWT bearer tokens

For interactive end-user clients, exchange a username and password for a short-lived access token plus a long-lived refresh token, then send the access token as Authorization: Bearer <jwt> on each subsequent request.

Step 1: log in.

curl -X POST https://geolens.example.com/api/auth/login/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=alice&password=hunter2"

Response shape:

{
  "access_token": "eyJhbGc...",
  "refresh_token": "...",
  "token_type": "bearer"
}

Step 2: use the access token.

curl https://geolens.example.com/api/collections/datasets/items \
  -H "Authorization: Bearer eyJhbGc..."

Refresh tokens. Access tokens are short-lived. When yours expires, exchange the refresh token for a new pair via POST /api/auth/refresh/. Refresh tokens rotate on every call, so store the new one and discard the old.

Where to store tokens. In the browser, store the access token in memory (not localStorage) and the refresh token in an httpOnly cookie. For server-side scripts, treat both like any other secret: environment variables or a secrets manager, never committed to source control.

API keys

API keys are long-lived credentials suitable for scripts, scheduled jobs, and machine clients. They can be passed two ways. The header form is preferred; the query-string form exists for tools that can’t easily set headers (notably ogr2ogr’s OAPIF: driver) and is deprecated for everything else (geolens#821), since a key in a URL lands in access and proxy logs. For which credential fits which client, and how each example sets the header (MapLibre transformRequest, the ArcGIS JS request interceptor, QGIS’s API Header authentication configuration, a DuckDB HTTP secret), start from the examples repo’s authentication section and the per-example READMEs.

Header form (preferred):

curl https://geolens.example.com/api/collections/datasets/items \
  -H "X-Api-Key: <your-api-key>"

Query-string form:

curl 'https://geolens.example.com/api/collections/datasets/items?api_key=<your-api-key>'

The header takes precedence over the query string. Never combine the two on the same request.

A key the server cannot resolve (revoked or mistyped) returns 401 on every endpoint that reads credentials from v1.14.0. Older releases discarded an unknown key on most routes and answered 200 with the public subset, which looks exactly like a smaller catalog, so a script whose key had lapsed kept working against less data. Requests that send no credential still get the public view.

Three cases sit outside that rule. POST /api/auth/logout/ accepts a dead access token so a stale session can still be cleared. A request that a valid X-Embed-Token or a valid signed tile template (sig, exp, scope) has already authorized is served and the dead key is ignored (an invalid or missing one puts the request back under the rule). And GET /api/maps/shared/{token} answers 404 for an unknown link and 410 for a revoked one whatever you send. The API reference overview carries the full statement.

Obtaining a key. Any signed-in user creates their own keys under Settings > API Keys in the web UI (POST /api/auth/api-keys/). Admins can also issue and revoke keys for other users from the user-management page; see User management & RBAC. Each key is scoped to a single user account and inherits that user’s permissions.

Security. API keys do not expire unless created with expires_at through the API. Rotate them on a schedule and revoke any key whose host environment changes. Treat a leaked API key the same as a leaked password.

OAuth / OIDC

GeoLens supports OAuth/OIDC sign-in via Google, Microsoft, and any generic OIDC provider, configured by an administrator. End users do not call the OAuth endpoints directly; they sign in through the GeoLens web UI, which performs the standard authorization-code flow on their behalf.

The browser flow:

1. User clicks “Sign in with <provider>” in the GeoLens UI.
2. UI redirects to https://geolens.example.com/api/auth/oauth/<provider>/login.
3. Provider authenticates the user and calls back to https://geolens.example.com/api/auth/oauth/<provider>/callback.
4. GeoLens issues a JWT and the UI stores it.

Once the UI has a JWT, machine clients reuse it like any other Bearer token:

curl https://geolens.example.com/api/collections/datasets/items \
  -H "Authorization: Bearer eyJhbGc..."

Provider setup. OIDC client registration and the list of supported providers are admin-configured. See OAuth/OIDC setup.

Out of scope. GeoLens does not currently support OIDC client-credentials or PKCE machine flows. Machine-to-machine clients should use API keys.

Browser clients and CORS

Anonymous requests to the standards and tile routes get Access-Control-Allow-Origin: *, so a page on another origin can read the public catalog and draw public tiles with no setup. As soon as a request carries a credential (X-Api-Key, Authorization, a cookie, or ?api_key=) the wildcard is gone: the page’s exact origin has to be listed in CORS_ALLOWED_ORIGINS, and a literal * there is rejected. See Settings -> Network.

Raster tiles began sending CORS headers in v1.13.0 (geolens#1464). That matters for loaders that fetch tiles with WebGL or fetch (MapLibre, the ArcGIS Maps SDK for JavaScript, OpenLayers with crossOrigin set), which draw an empty map against an older instance while the server returns valid PNGs. <img>-based loaders (Leaflet, OpenLayers by default) render the same tiles either way.