User Management & RBAC

GeoLens uses role-based access control with three default roles. Most day-to-day administration happens through the admin web UI at /admin; the same actions are available via the REST API for scripting and automation.

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

Roles & permissions

The default role hierarchy is viewer → editor → admin. The exact permission matrix is defined in code at backend/app/modules/auth/permissions.py and can be customized by an admin via Admin → Settings → Permissions.

Capability	viewer	editor	admin
`upload` (upload data files)	✗	✓	✓
`create_layers` (create empty layers)	✗	✓	✓
`export` (export datasets)	✓	✓	✓
`edit_metadata` (edit dataset metadata)	✗	✓	✓
`manage_collections` (create/delete collections)	✗	✓	✓
`use_ai_chat` (use AI styling/chat)	✗	✓	✓
`manage_users` (create/edit users)	✗	✗	✓
`manage_settings` (edit system settings)	✗	✗	✓

The matrix is checked on every authenticated request via the require_permission() dependency. A user receives a 403 Forbidden if their role lacks the capability for the requested endpoint, regardless of dataset visibility.

Self-registration approval

GeoLens ships with self-registration disabled by default. With REGISTRATION_ENABLED=true in .env, the login screen exposes a Sign up link; new accounts created through it land in a pending state and require an admin to approve them before they can log in.

To enable:

REGISTRATION_ENABLED=true

Pending users appear in Admin → Users filtered by status. Approve by changing the status to active or by editing the user record. Until approved, login attempts return 403 Forbidden — account pending approval.

For SSO-managed organizations, leave REGISTRATION_ENABLED=false and provision users through OAuth/OIDC. See OAuth/OIDC setup for the four-provider configuration walkthrough.

Managing users via the admin UI

Navigate to Admin → Users to see every account on the instance. The list shows username, email, role, status (active, disabled, pending), last login, and creation date. The header + Add User button opens the create dialog.

The create dialog requires a username, password, and role. The username is the unique identifier used for login and audit logs; the password must meet the configured minimum length (default 8 characters). Role is required and defaults to viewer.

To deactivate a user without deleting their data, use the Deactivate menu action on the row. Deactivated users keep all their datasets, maps, and collections — they simply can’t log in. Reactivate by toggling the status back to active. Deleting a user is permanent and cascades to API keys, saved searches, and OAuth links; transfer ownership of important datasets first.

Managing users via the API

All user-administration endpoints require the manage_users capability (admin role). Obtain a JWT token first:

TOKEN=$(curl -s -X POST https://geolens.example.com/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin" | jq -r '.access_token')

Create a user

curl -X POST https://geolens.example.com/api/admin/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "analyst1",
    "password": "secure-password",
    "role": "editor"
  }'

List all users

curl https://geolens.example.com/api/admin/users \
  -H "Authorization: Bearer $TOKEN"

Supports pagination: ?skip=0&limit=50.

Get a specific user

curl https://geolens.example.com/api/admin/users/{user_id} \
  -H "Authorization: Bearer $TOKEN"

Update a user

curl -X PATCH https://geolens.example.com/api/admin/users/{user_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Updating a role takes effect on the next request — JWT tokens already issued retain the old role until they expire (default 15 minutes). For immediate revocation, deactivate the account instead.

Deactivate a user

Deactivating a user prevents them from logging in without deleting their data:

curl -X POST https://geolens.example.com/api/admin/users/{user_id}/deactivate \
  -H "Authorization: Bearer $TOKEN"

API keys

API keys are long-lived credentials suitable for scripts, scheduled jobs, and machine clients. Each key is scoped to a single user account and inherits that user’s permissions — there is no separate “service account” role.

Issuing a key (admin UI)

Navigate to Admin → Users and click into the target user.
Open the API Keys panel.
Click + New Key, add a label (e.g., “ETL pipeline 2026-01”), and copy the key value when shown.

The key value is shown once — there is no way to retrieve it again. If lost, revoke the key and issue a new one. Keys are stored as bcrypt hashes; only the prefix (glk_live_...) is recoverable from the database.

Issuing a key (API)

curl -X POST https://geolens.example.com/api/admin/api-keys/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "{user_id}",
    "label": "ETL pipeline 2026-01"
  }'

The response includes the full key value — capture it immediately. Subsequent reads (GET /api/admin/api-keys/) return only the prefix and metadata.

Revoking a key

curl -X DELETE https://geolens.example.com/api/admin/api-keys/{key_id} \
  -H "Authorization: Bearer $TOKEN"

Revocation takes effect on the next request. There is no “rotate” operation — issue a new key, update consumers, then revoke the old one.

For the request-side details (header form vs query-string form, resolution order against JWT and OAuth), see API authentication.

Other admin tools

The admin web UI (/admin) exposes several operator tools beyond user management. The most useful are:

Audit Log (/admin/audit) — Browse and filter the full audit log with action, user, resource, and date filters. Supports CSV and JSON export. Use this page to investigate “who changed what” without writing API queries.
Jobs (/admin/jobs) — Lists all ingestion jobs across all users with status, source filename, and timing. Failed jobs link to the error message and the user who started them. Useful for triaging stuck or repeatedly failing imports.
Shared Maps (/admin/shared-maps) — System-wide view of every share and embed token created on the instance. Shows map title, owner, expiry, allowed origins, and view count. Tokens can be revoked from this page without finding the parent map first. Use this to audit external sharing, especially before public events or when rotating leaked tokens.
Config Ops (/admin/config-ops) — Export the entire instance configuration (settings + OAuth providers, secrets redacted) as a JSON file, or import a previously exported configuration in either merge or overwrite mode. The dry-run button shows exactly what would change before applying anything. Use this to copy configuration between dev/staging/prod instances or to back up settings before major upgrades.

The companion Validate Connectivity button on Config Ops probes storage, cache, and every enabled OIDC provider and reports per-provider latency and error details — useful for diagnosing post-deployment issues without SSH access. See Infrastructure & Monitoring for the connectivity-probe details.