Skip to content
getgeolens.com

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, GitHub, Microsoft, or generic OIDC providers.

Resolution order on every request: X-Api-Key header -> an API key as the password of an HTTP Basic login (reads only, from v1.28.0) -> ?api_key= query parameter (reads only, from v1.18.1) -> Authorization: Bearer <jwt> header -> anonymous. The first match wins.

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

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.

Terminal window
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",
"expires_in": 900
}

expires_in is the number of seconds until the access token expires — schedule your refresh from it. refresh_token is null when the caller opted into the browser cookie flow described below.

Step 2: use the access token.

Terminal window
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, keep the access token in memory (not localStorage) and let GeoLens hold the refresh token for you: send X-GeoLens-Auth-Mode: cookie on POST /api/auth/login and the server returns the refresh token as an httpOnly cookie with a null refresh_token in the body. Login also sets a second cookie, geolens_csrf, which is deliberately not httpOnly so your script can read it. POST /api/auth/refresh/ with the same header reads the refresh cookie and requires you to echo that value back in an X-CSRF-Token header — the double-submit check compares the two and answers 403 when they disagree. Programmatic callers (CLI, SDKs, CI) omit the header and keep the body token. For server-side scripts, treat both like any other secret: environment variables or a secrets manager, never committed to source control.

Since 1.25.0, password sign-in is limited per account as well as per address (the per-address limit is LOGIN_RATE_LIMIT). After 10 failed sign-ins to one account within an hour, POST /api/auth/login answers 429 with a Retry-After header and {"detail": {"code": "login_throttled", "message": "..."}} for any client the account does not know, even when the password is right. Existing and unknown usernames get the same count, status and timing.

A browser that has signed in to the account before carries an HttpOnly geolens_device_* cookie (180 days, at most five per browser, cookie auth mode only) and keeps its own budget, so a guesser elsewhere cannot lock the owner out. Bearer tokens, API keys and refresh are not affected. Each throttle writes one user.login.throttled audit row per window. Shared service accounts should use API keys instead of passwords.

To let an admin back in from a new browser, run this on the host. It prints a single-use link, valid for 10 minutes, to a /login/trust confirmation page:

Terminal window
docker compose exec api /app/.venv/bin/python -m scripts.trust_login_device <username>

POST /api/auth/change-password/ has its own budget of 10 failed current-password checks per account per hour. After that it answers 429 with Retry-After and {"detail": {"code": "password_change_throttled", "message": "..."}}, even for a correct password. The two budgets are separate, so failed sign-ins cannot block a password change or the reverse.

POST /api/auth/logout/ revokes the account’s access and refresh tokens across all devices. The web UI’s Sign out action uses this endpoint. API keys remain valid; revoke them separately when needed.

Since 1.20.0, POST /api/auth/logout/session/ revokes the refresh tokens from one login without signing out other devices. Access tokens from that login remain valid until their normal expiry.

Reusing a rotated refresh token after the concurrency grace period, while that token is still within its original lifetime, revokes only that login’s refresh tokens. Keep the new token after each refresh; a client affected by replay rejection must sign in again. Account-wide logout and password-reset revocation remain unchanged.

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 clients that can only be handed a bare URL and is deprecated elsewhere because a key in a URL lands in access and proxy logs. Most tools can set the header — ogr2ogr and ogrinfo take --config GDAL_HTTP_HEADERS "X-Api-Key: <your-api-key>". 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):

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

Query-string form (deprecated; supported until at least 2027-02-05):

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

From v1.18.1 the query-string form authenticates only GET, HEAD and OPTIONS requests, minus the few GETs that write (the same ones a read_only key is refused). On anything else, POST /api/stac/search and POST /api/query/ included, a key in the query string is treated as absent, so a request that relied on it answers as if unauthenticated. Move such clients to the X-Api-Key header.

Send the key in the X-Api-Key header, or as the password of an HTTP Basic login, before 2027-02-05.

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

HTTP Basic form. From v1.28.0 a key also authenticates as the password of an HTTP Basic login; the username is ignored. Like the query string, it works for GET, HEAD and OPTIONS only and does not get the read-only POST carve-outs below. A Basic login on another method, a malformed one, or one whose password isn’t a live key answers 401 with WWW-Authenticate: Basic realm="GeoLens". Account passwords are never accepted this way. This lane exists for desktop clients that can only save a login, such as ArcGIS Pro.

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. Creating a key needs a signed-in session. POST /api/auth/api-keys/ and POST /api/admin/api-keys/ answer 403 to a request that presents an API key, so a key cannot mint another key. Any signed-in user creates their own keys under Settings > API Keys in the web UI (POST /api/auth/api-keys/) — see Account settings -> API Keys for that form, what the reveal dialog does, and how the list reads. Admins can also issue and revoke keys for other users from the user-management page (POST /api/admin/api-keys/); see User management & RBAC. Each key belongs to exactly one user account, and what it can do is that user’s permissions narrowed by the key’s own scope.

Keys minted from v1.27.0 start with glk_ and are 47 characters long, so secret scanners can recognise a pasted key and the server redacts one from its logs. Older keys keep working.

Key scope. Every key is minted full, publish or read_only, or, for a key bound to one dataset, dataset_write or dataset_append (see below). The scope field on the create request sets it and defaults to "full"; both mint forms in the UI offer the same Full access / Publish / Read only picker, also defaulting to full. A full key acts as the owner, with exactly the owner’s permissions. A read_only key authenticates GET, HEAD, and OPTIONS only. Four POST routes are carve-outs because they are reads that happen to be POSTs: POST /api/query/ (the read-only SQL sandbox), POST /api/stac/search, POST /api/jobs/status/ and POST /api/datasets/{id}/aggregate/. One GET is refused despite its method — GET /api/datasets/{id}/validate/?refresh=true, which recomputes and persists a quality score; the same route without refresh, or with a false-y value, serves the cached result normally. Scope is fixed at creation, so changing it means minting a new key and revoking the old one. Pick read_only for dashboards, CI checks, and anything that only ever fetches.

Anything else a read_only key asks for is refused while the key is being resolved, before the handler runs, with 403 and an RFC 7807 body:

{
"type": "about:blank",
"title": "Forbidden",
"status": 403,
"detail": "This API key is read-only"
}

From v1.27.0 a publish key can do what a read_only key can, and also upload and import, apply manifests, edit its owner’s dataset metadata, create and import maps, and replace an uploaded dataset’s data. A replacement keeps the replaced data as a previous version, as a re-upload in the app does, up to the instance’s limit on kept versions. A publish key acts only on its owner’s own objects, even when the owner is an admin. It can’t update an existing map (PUT /api/maps/{id}; a republish creates a new map), delete anything, write features, write stories, reach admin or key routes, or replace a raster dataset or one bound to a service, STAC item or table. It also can’t make anything public: a request for public visibility is refused, an update may keep or narrow a dataset’s visibility but not widen it, and an unpublished public dataset can’t be published. Its refusals are 403 with detail.code == "api_key_scope". Pick publish for pipelines that load data and leave publishing to a person.

Dataset keys. From v1.26.0, an editor can mint a key bound to one dataset. A dataset_write key reads and writes that dataset’s features and nothing else. A dataset_append key can only create features, so a leaked key cannot read or change data, which suits webhooks and IoT feeds. Both must expire within 365 days, act as the user who minted them, and write even when Enable Dataset Editing is off. Anywhere else they are answered as an invalid key. Mint them with POST /api/datasets/{dataset_id}/api-keys. See Write features through the API.

Expiry. expires_at is optional on full, publish and read-only keys. From v1.26.0 the create forms in Settings and on the admin user page offer Never (the default), 30 days, 90 days and 1 year, and each key in the list shows when it expires. A key past its expiry is marked Expired and no longer authenticates.

Security. API keys do not expire unless created with an expiry, but they are invalidated by security events on the owner’s account: a password change, a role change, or an admin approving a pending account all stop every existing key for that user from resolving. Signing out of the web UI deliberately does not. Rotate keys on a schedule and revoke any key whose host environment changes. Treat a leaked API key the same as a leaked password.

GeoLens supports OAuth/OIDC sign-in via Google, GitHub, Microsoft Entra ID, and any generic OIDC provider, configured by an administrator. (GitHub is plain OAuth 2.0 rather than OIDC; OAuth/OIDC setup covers the difference.) 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:

Terminal window
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.

Anonymous requests to the standards routes and, from v1.14.1, to the anonymous catalog-search routes GET /api/search/datasets/ and GET /api/search/facets/ get Access-Control-Allow-Origin: *, so a page on another origin can read the public catalog with no setup.

From v1.27.0 a request that sends an API key in the X-Api-Key header can be read from any origin too, so a page or notebook can call the instance with a pasted key and no allowlist entry. The answer carries Access-Control-Allow-Origin: * without Access-Control-Allow-Credentials, on routes that check the key, and cookies sent with the request are ignored. The sign-in, registration and session routes under /api/auth/ refuse a keyed preflight. Because of this, CORS_ALLOWED_ORIGINS does not limit which pages can use a key someone has pasted into them.

From v1.32.0 the anonymous wildcard also covers the native reads of public content: GET /api/maps/{id}, /api/maps/{id}/style.json, the /api/maps/sprites/geolens sprite sheets, /api/stories/, /api/stories/{id}, /api/datasets/{id}/rows/ and /api/capabilities/, plus the preflight for POST /api/datasets/{id}/aggregate/. They return only what an anonymous caller could already read, and the write routes on the same paths still need the allowlist.

From v1.32.0 a GET or HEAD whose only credential is an API key in ?api_key= is readable from any origin as well, for clients such as ArcGIS Online Map Viewer that put the key in the layer URL. The answer gets the wildcard only once the key is accepted, so an unknown, expired or revoked key gets no CORS headers, and cookies sent with the request are dropped.

Any other credential (Authorization, a cookie, an embed token, ?embed_token= in the URL, or a key sent both in X-Api-Key and in ?api_key=) needs the page’s exact origin listed in CORS_ALLOWED_ORIGINS, and a literal * there is rejected. See Settings -> Network.

Tile routes work differently. Served vector and cluster tiles (200 and 204), tile 429s and tile query-timeout 503s answer with a static Access-Control-Allow-Origin: *, credential or not, and raster tiles behind the bundled nginx send it on every status, raster 429s included, because a tile URL template carries its authorization in the query string (sig, exp, scope, or the deprecated ?api_key=) and the response is cacheable. A cross-origin page can therefore draw a signed private tile with no CORS_ALLOWED_ORIGINS entry. A tile fetch that sets X-Api-Key as a header is preflighted and, from v1.27.0, falls under the header-key rule above, so it needs no entry either. Errors on a signed or query-key vector or cluster tile URL (401, 403, 404) carry no wildcard, so a page on an unlisted origin cannot read their status.

Raster tiles began sending CORS headers in v1.13.0. 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.