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 — 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).

Header form (preferred):

curl https://geolens.example.com/api/collections/datasets/items \
  -H "X-Api-Key: glk_live_..."

Query-string form:

curl 'https://geolens.example.com/api/collections/datasets/items?api_key=glk_live_...'

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

Obtaining a key. API keys are issued from the admin 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. 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, group-to-role mapping, and the list of supported providers are all 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.