Authentication

Topolab has two authentication schemes, and which one you use depends on what you are calling:

• X-API-Key for machine and data access, the dataset, OGC, SQL, and catalogue endpoints.
• Authorization: Bearer <session JWT> for portal and account endpoints, API-key management, credits and usage, invoices, organization, and Data Studio.

Human sign-in is passwordless (magic link); machines use API keys. You cannot mint an API key with an API key, key management runs on the portal session (Bearer) only.

API keys (machine access)

Create a key in the account portal under API keys, or via the Bearer-authenticated API. Keys carry a scope and permissions, and the secret is shown only once at creation.

• Header: X-API-Key
• Format: tlb_{env}_{32 chars}, for example tlb_prod_3f9a2c7e8b1d4056a1c2e3f4a5b6c7d8
• Scopes: user, organization, platform
• Permissions: a permission (READ, WRITE, or ADMIN) bound to a resource (DATASET, COORDINATES, ARCHIVES, DATA, BILLING, USERS, and more). For example a dataset download needs READ on DATASET; OGC access needs READ on COORDINATES; SQL needs READ on DATA.

curl -H "X-API-Key: tlb_prod_..." \
  "https://api.topolab.nl/v1/dataset/transport_infrastructure_bushaltes/files/geojson"

See API keys for the full permission×resource reference.

Some endpoints additionally require an addon on your organization:

Capability	Required addon
Dataset downloads & coordinates	API_ACCESS
OGC collections & features	GIS_ACCESS
Historical archives	ARCHIVED_DATA

Bearer tokens (account endpoints)

Account, organization, billing, and Data Studio endpoints are called on behalf of a signed-in user with a Bearer JWT:

curl -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/organization/me"

You obtain the token by signing in (passwordless magic link) through the portal. Use API keys, not Bearer tokens, for unattended/server-to-server data access.

Managing keys

Key management runs on the portal session, so these endpoints take a Bearer JWT, not an X-API-Key:

• POST /v1/api-keys/personal, create a personal key (the secret is returned once)
• GET /v1/api-keys/my-keys, list your personal keys
• GET /v1/api-keys/:id/usage, usage stats for a key

See API keys for the full reference.

Good practice

• Treat keys like passwords, never commit them. Load from an environment variable.
• Rotate on a schedule and immediately if a key may be exposed.
• Use organization-scoped keys for shared/server use, personal keys for individual work.