API-sleutels en scopes

Elk request aan de Sursa API wordt gedaan met een API-sleutel van je organisatie. Een sleutel hoort bij de organisatie, niet bij een persoon: hij blijft werken als de medewerker die hem heeft gemaakt, vertrekt, en wat hij mag, is op de sleutel zelf ingesteld.

Wat een sleutel mag doen

Drie instellingen van een sleutel bepalen wat een request ermee kan zien en wijzigen. Elke instelling beperkt de andere alleen verder.

Instelling	Wat ze bepaalt
Rol	`admin`, `editor`, `verifier` of `viewer`, dezelfde rollen als mensen hebben. De sleutel kan doen wat een gebruiker met die rol kan doen.
Scopes	Welke delen van de API de sleutel mag aanroepen, bijvoorbeeld `cards:read` of `webhooks:manage`. Zie Scopes van sleutels.
Dataprofiel	Optioneel. Beperkt de sleutel tot de categorieën kennis die het profiel toestaat, net als een gebruiker met dat profiel.

Een sleutel kan ook worden beperkt tot bepaalde collecties en een verloopdatum krijgen. Een request buiten deze grenzen mislukt: een ontbrekende scope geeft 403 met de code api_keys.scope, en een object dat de sleutel niet kan zien, geeft 404, precies alsof het niet bestaat.

Geef elke integratie een eigen sleutel met de beperktste rol en scopes die ze nodig heeft. Een synchronisatiejob die alleen documenten schrijft, heeft geen admin nodig; een rapportagejob heeft geen scopes voor schrijven nodig.

Een sleutel maken

Een beheerder van de organisatie maakt sleutels in Sursa onder Administration → API keys (beheer → API-sleutels), of met POST /v1/api-keys en een sleutel of sessie met de rol admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

De response bevat de waarde van de sleutel in key. Die wordt één keer getoond: Sursa bewaart er alleen een hash van en kan hem niet nog eens tonen. Een sleutel ziet eruit als kb_ gevolgd door 43 tekens; de eerste tekens (prefix) worden getoond in de lijst met sleutels, zodat je sleutels uit elkaar kunt houden.

Zonder scopes krijgt de sleutel de scopes van zijn rol. Geef scopes mee om hem verder te beperken. Zonder expires_at verloopt de sleutel niet.

Sleutels geheimhouden

Bewaar sleutels in een secretmanager of in omgevingsvariabelen van je dienst, nooit in de broncode.
Gebruik sleutels alleen vanaf je servers. Sursa accepteert requests uit browsers (CORS staat open), maar een sleutel in een webpagina is zichtbaar voor iedereen die de pagina opent.
Stuur een sleutel nooit mee in een URL. Stuur hem alleen in de header Authorization.
Is een sleutel uitgelekt, trek hem dan meteen in en maak een nieuwe.

Een sleutel controleren

GET /v1/me geeft de sleutel terug met zijn rol, effectieve scopes, dataprofiel, verloopdatum en snelheidslimiet. Het werkt met elke geldige sleutel, welke scopes die ook heeft, dus gebruik het als verbindingstest van je integratie en wanneer je een 403 onderzoekt.

Een sleutel roteren

Bij rotatie vervang je een sleutel zonder de integratie te stoppen. De snelste manier is de sleutel zelf te roteren: POST /v1/api-keys/{key_id}/roll geeft een nieuwe waarde uit voor dezelfde sleutel, met dezelfde rol, scopes, collecties en verloopdatum. De vorige waarde blijft overlap_hours lang werken (standaard 24 uur, maximaal 168), zodat je in de tussentijd de nieuwe waarde kunt uitrollen; POST /v1/api-keys/{key_id}/revoke-previous beëindigt de overlap eerder.

Wil je de sleutel in plaats daarvan door een andere sleutel vervangen:

Maak een nieuwe sleutel met dezelfde rol, scopes en hetzelfde dataprofiel.
Zet de nieuwe sleutel in je integratie.
Houd de oude sleutel in de gaten onder Administration → API keys (of last_used in GET /v1/api-keys) tot hij niet meer wordt gebruikt.
Trek de oude sleutel in.

Stel een verloopdatum in op sleutels en roteer ze vóór die datum. Sursa waarschuwt de beheerders van de organisatie voordat een sleutel verloopt; een verlopen sleutel geeft 401 met de code api_keys.expired.

Een sleutel intrekken

Trek een sleutel in onder Administration → API keys of met DELETE /v1/api-keys/{key_id}. De intrekking gaat binnen enkele seconden in op elke API-server. Requests met een ingetrokken sleutel geven 401 met de code auth.not_authenticated.

Sleutels van een eigen bron

Een eigen bron heeft een eigen soort sleutel. Die begint met kbsrc_, kan alleen documenten naar die ene bron schrijven en kan niets lezen of zoeken. Het is de veiligste sleutel om aan een integratieplatform zoals Zapier te geven. Maak hem op de pagina van de bron onder API keys of met POST /v1/sources/{source_id}/push-keys.

Als sleutels niet beschikbaar zijn

API-sleutels maken deel uit van het abonnement van de organisatie. Omvat het abonnement ze niet, dan geven het maken van een sleutel en elk request met een sleutel 403 met de code api_keys.feature_disabled.