De Public API is bearer-token, tenant-scoped REST. Base path: /api/public/v1/. Stappen voor de eindgebruiker en de endpoint-catalogus staan in de user API guide. Deze pagina is de operationele kijk.
Key-model
Elke API-key:
- Is tenant-scoped. Een key authenticeert als de tenant, niet als individuele gebruiker.
- Heeft een prefix (de eerste 12 tekens, bv.
fck_live_a1b2) die in de UI getoond wordt zodat je 'm kunt herkennen zonder het volledige token bloot te leggen. - Wordt one-way gehasht opgeslagen. Het volledige token wordt eenmalig getoond bij aanmaak en daarna nooit meer — zelfs een admin met volledige databasetoegang kan het niet terughalen.
- Heeft een set scopes (
issues:read,issues:write,patches:read,patches:write,integrations:read,webhooks:read,webhooks:write). - Heeft een naam (jouw label), een created by-gebruiker, en created-, last used- en revoked-timestamps.
Intrekken is non-destructief: de key werkt direct niet meer, maar het record blijft staan voor audit. Authenticeren met een ingetrokken key geeft 401 met code: invalid_token.
Authenticatie-fouten
| Situatie | HTTP | code |
|---|---|---|
Geen Authorization-header | 401 | missing_token |
| Onbekende of ingetrokken key | 401 | invalid_token |
| Geldige key, verkeerde scope voor het endpoint | 403 | insufficient_scope |
| Boven de per-key rate limit | 429 | rate_limited |
Rate limits
Default: 60 requests per minuut per key, met bursts van maximaal 60 en daarna een aanhoudende 1 request / seconde nadat de burst opgemaakt is. Bij overschrijden volgt 429 met een Retry-After-header en code: rate_limited.
Limieten worden per key bijgehouden, niet per tenant. Twee keys binnen dezelfde tenant delen geen budget, zodat één doorgedraaide integratie een andere niet kan verdrinken. Neem contact op met support als je voor een specifieke key een hogere tier nodig hebt.
Scopes
Er zijn 7 scopes:
| Scope | Endpoints |
|---|---|
issues:read | GET /issues, GET /issues/:key |
issues:write | POST /issues |
patches:read | GET /patches, GET /patches/:id |
patches:write | gereserveerd — vandaag geen endpoints |
integrations:read | GET /integrations/status |
webhooks:read | GET /webhooks |
webhooks:write | POST /webhooks |
Een key zonder enige scope kan authenticeren maar elk geautoriseerd endpoint geeft 403. Handig als canary: "geef me een seintje wanneer deze key ergens gebruikt wordt waar ik 'm niet verwachtte".
Audit
Elke API-request — succes en elke faalmodus — landt in het audit-log:
event—public_api.usedbij succes,public_api.auth_failedbij elke faalmodus.tenant— de tenant waar de key bij hoort (of leeg als het token niet resolved).targetKind: "api_key",targetId— welke key gebruikt is (of leeg bij een unresolved bearer).fields.reason— bij failures:missing_token,invalid_token,missing_scope,rate_limited.fields.scope— de scope die het endpoint vereiste.fields.path— het request-pad.
Waarom ook auditen op failures: een geauthenticeerde API is je externe aanvalsoppervlak. Een scanner die random tokens probeert of hamert op een scope die 'ie niet hoort te hebben is een leading indicator van compromise, en het audit-log is de duurzame neerslag waar je op kunt reviewen en alerten.
OpenAPI
De OpenAPI 3.1-spec wordt geserveerd op /api/public/v1/openapi.json. Wijs elke OpenAPI-aware client (Postman, Insomnia, code-generators) naar die URL voor een actuele beschrijving van elk endpoint, request- en response-vorm.
Operationele richtlijnen
- Eén key per integratie. Makkelijker roteren, makkelijker auditen, makkelijker scopen.
- Genereer geen key met alle scopes "voor de zekerheid". Beperk de blast radius.
- Roteer op een vast tempo. 90 dagen is redelijk voor high-traffic keys; langer kan voor low-traffic keys mits je audit-alerts hebt.
- Wire de `request_id` uit API-responses door naar je client-logs. Wanneer een API-call faalt kan support correleren op request id; de jouwe meedelen scheelt een round-trip.
- Webhooks zijn beter dan polling. Een poll-loop op
GET /issuesmag, maar is verspilling — abonneer een outbound webhook opissue.*events en reageer daarop.
FAQ
Is de Public API hetzelfde als de interne API van het dashboard? Nee. Het dashboard gebruikt interne routes die een ingelogde sessie vereisen en niet stabiel zijn. De Public API op /api/public/v1/... is wat wij committen — versioned, OpenAPI-beschreven, en breaking changes gaan via deprecation-meldingen.
Kan een key meer dan één tenant aan? Nooit. By design.
Waarom is er wel een `integrations:read` scope maar geen `integrations:write`? Vandaag exposed de public API alleen de read-only health snapshot. Integraties muteren is een UI-flow want dat vereist multi-step OAuth handshakes die niet schoon onder bearer-token write-semantiek passen.
Wat is de SLA? Beschikbaarheidsdoelen en incident-comms zijn deel van je abonnement, niet van de docs. Voor de operationele details: /contact.