Aan de slag
GA

Authenticatie

Hoe je je kunt authentiseren bij de Topolab API — maak API-sleutels aan, stuur de X-API-Key header en gebruik Bearer-tokens voor account-eindpunten.

Authenticatie

Topolab heeft twee authenticatiepaden: API-sleutels voor machine- en data-toegang, en Bearer-tokens voor account- en portal-eindpunten. Menselijke aanmelding is wachtwoordloos (magische link); machines gebruiken API-sleutels.

API-sleutels (machine toegang)

Maak een sleutel aan in het accountportaal onder API-sleutels, of via de API. Sleutels hebben een scope en rechten, en het geheim wordt slechts één keer getoond bij aanmaak.

  • Header: X-API-Key
  • Formaat: tlb_{env}_{32 tekens} — bijvoorbeeld tlb_prod_3f9a2c7e8b1d4056a1c2e3f4a5b6c7d8
  • Scopes: gebruiker, organisatie, platform
  • Rechten: lezen, schrijven (data-toegang heeft read nodig op de relevante bron)
curl -H "X-API-Key: tlb_prod_..." \
  "https://api.topolab.nl/v1/dataset/nl-domino-poi/files/geojson"

Sommige eindpunten vereisen bovendien een add-on voor jouw organisatie:

Functionaliteit Vereiste add-on
Dataset downloads & coördinaten API_ACCESS
OGC-collecties & features GIS_ACCESS
Historische archieven ARCHIVED_DATA

Bearer-tokens (account-eindpunten)

Account-, organisatie-, facturering- en Data Studio-eindpunten worden aangeroepen namens een ingelogde gebruiker met een Bearer JWT:

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

Je verkrijgt de token door in te loggen (wachtwoordloze magische link) via het portaal. Gebruik API-sleutels, niet Bearer-tokens, voor ongecontroleerde/server-naar-server data-toegang.

Sleutels beheren

De API-sleutels eindpunten laten je sleutels aanmaken, opsommen, roteren, intrekken en gebruik inspecteren:

  • GET /v1/api-keys/my-keys — jouw persoonlijke sleutels
  • POST /v1/api-keys/personal — maak een persoonlijke sleutel aan
  • POST /v1/api-keys/:id/rotate — roteer (geeft een nieuw geheim uit, trekt het oude onmiddellijk in)
  • POST /v1/api-keys/:id/revoke — intrekken
  • GET /v1/api-keys/:id/usage — gebruiksstatistieken

Zie API-sleutels voor de volledige referentie.

Goede praktijk

  • Behandel sleutels als wachtwoorden — commit ze nooit. Laad ze vanuit een omgevingsvariabele.
  • Rotate volgens een schema en onmiddellijk als een sleutel mogelijk is blootgesteld.
  • Gebruik organisatie-gescopeerde sleutels voor gedeeld/servergebruik, persoonlijke sleutels voor individueel werk.