API-sleutels

Beheer de API-sleutels die machine- en data-toegang authenticeren. Deze beheereindpunten gebruiken een Bearer JWT (de ingelogde gebruiker), terwijl de sleutels zelf worden verzonden als X-API-Key bij dataverzoeken. Zie Authenticatie.

Sleutelmodel

• Formaat: tlb_{env}_{32 chars} — bijvoorbeeld tlb_prod_3f9a2c7e8b1d4056a1c2e3f4a5b6c7d8.
• Geheim: eenmaal getoond in de aanmaak- en rotatie-antwoorden. Het is daarna niet meer op te halen.
• Scopes: user, organization, platform.
• Permissies: controleer wat de sleutel mag doen; data-toegang heeft read nodig op de relevante bron.

Persoonlijke sleutels behoren tot jou binnen een organisatie. Organisatie-sleutels worden gedeeld en beheerd op het organisatieniveau; het aanmaken of bekijken ervan vereist de APIKEY_VIEW / APIKEY_CREATE permissies.

Lijst sleutels

GET /v1/api-keys/my-keys          # jouw persoonlijke sleutels
GET /v1/api-keys/accessible       # elke sleutel die je kunt zien

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

{
  "data": [
    {
      "id": "key_9a2c7e8b",
      "name": "etl-nightly",
      "scope": "organization",
      "permissions": ["read"],
      "prefix": "tlb_prod_3f9a2c7e",
      "expiresAt": "2026-12-31T23:59:59Z",
      "createdAt": "2026-05-01T09:14:00Z"
    }
  ]
}

Het geheim wordt nooit teruggegeven door lijst-eindpunten — alleen de prefix wordt getoond ter identificatie.

Maak een persoonlijke sleutel

POST /v1/api-keys/personal

curl -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"name":"etl-nightly","permissions":["read"],"expiresAt":"2026-12-31T23:59:59Z"}' \
  "https://api.topolab.nl/v1/api-keys/personal"

De respons bevat het volledige geheim. Dit is de enige keer dat het wordt teruggegeven — sla het nu op.

{
  "id": "key_9a2c7e8b",
  "name": "etl-nightly",
  "scope": "user",
  "permissions": ["read"],
  "secret": "tlb_prod_3f9a2c7e8b1d4056a1c2e3f4a5b6c7d8",
  "expiresAt": "2026-12-31T23:59:59Z",
  "createdAt": "2026-05-01T09:14:00Z"
}

Veld	Beschrijving
id	Sleutelidentificatie, gebruikt in de per-sleutel eindpunten hieronder.
secret	De volledige tlb_... sleutel. Eenmaal getoond. Stuur het als X-API-Key.
scope	user voor persoonlijke sleutels.
permissions	Toegekende permissies.
expiresAt	Optionele vervaldatum; laat weg voor een niet-vervallende sleutel.

Haal een sleutel op en werk deze bij

GET   /v1/api-keys/:id
PATCH /v1/api-keys/:id

PATCH werkt de naam, permissies of vervaldatum bij. Het retourneert of verandert het geheim niet.

curl -X PATCH \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"name":"etl-nightly-readonly","permissions":["read"]}' \
  "https://api.topolab.nl/v1/api-keys/key_9a2c7e8b"

Rotate een sleutel

POST /v1/api-keys/:id/rotate

Geeft een nieuw geheim uit en trekt de oude onmiddellijk in. Elke client die de oude geheim nog gebruikt, zal beginnen met het ontvangen van 401. Werk je implementatie bij vóór of gelijktijdig met de rotatie.

curl -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/api-keys/key_9a2c7e8b/rotate"

{
  "id": "key_9a2c7e8b",
  "secret": "tlb_prod_a1c2e3f4a5b6c7d83f9a2c7e8b1d4056",
  "rotatedAt": "2026-05-29T11:02:00Z"
}

Net als bij het aanmaken, wordt het nieuwe secret eenmaal getoond.

Intrekken en verwijderen

POST   /v1/api-keys/:id/revoke   # de sleutel uitschakelen, het record behouden
DELETE /v1/api-keys/:id          # de sleutel verwijderen

curl -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/api-keys/key_9a2c7e8b/revoke"

curl -X DELETE \
  -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/api-keys/key_9a2c7e8b"

Intrekken wanneer een sleutel mogelijk is blootgesteld, maar je wilt de geschiedenis behouden; verwijderen om het volledig te verwijderen.

Per-sleutel gebruik

GET /v1/api-keys/:id/usage?startDate=&endDate=

Geeft de oproepen en credits terug die aan één sleutel zijn toegeschreven over een ISO 8601 datumbereik.

curl -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/api-keys/key_9a2c7e8b/usage?startDate=2026-05-01&endDate=2026-05-31"

Voor organisatiebrede rapportage zie Gebruik statistieken.

Organisatie sleutels

Gedeelde sleutels worden beheerd onder de organisatie. Lijst vereist APIKEY_VIEW; creëren vereist APIKEY_CREATE.

GET  /v1/api-keys/organization/:organizationId
POST /v1/api-keys/organization/:organizationId

curl -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"name":"shared-backend","permissions":["read"]}' \
  "https://api.topolab.nl/v1/api-keys/organization/org_8f3a2c7e"

De aanmaakrespons retourneert het geheim eenmaal, zoals bij persoonlijke sleutels. Los organizationId op van Organisatie.

Fouten

Status	Betekenis
401	Ontbrekende of ongeldige Bearer-token.
403	Je hebt de vereiste permissie (bijvoorbeeld APIKEY_CREATE) voor de organisatie niet.
404	De sleutel of organisatie bestaat niet.
429	Rate limited — zie Rate limieten & credits.

Goede praktijk

• Vang het geheim bij creatie; rotatie is het enige herstel als het verloren gaat.
• Geef de voorkeur aan organisatie-sleutels voor gedeeld/server gebruik, persoonlijke sleutels voor individueel werk.
• Stel een expiresAt in en roteer volgens een schema.
• Intrek onmiddellijk als een sleutel mogelijk is blootgesteld.
• Heb je meer sleutels of hogere limieten nodig? Neem contact met ons op.