Direct naar inhoud

Aan de slag

Authenticatie met API-sleutels

Elk verzoek stuurt een organisatie-API-sleutel mee als Bearer token. Zo maak, gebruik en trek je sleutels in.

Bearer token

Stuur de sleutel mee in de Authorization-header. Gebruik altijd HTTPS, zodat de sleutel nooit onversleuteld over het netwerk gaat.

GET /api/v1/me HTTP/1.1
Host: factora.one
Authorization: Bearer factora_<64 tekens>
Accept: application/json

Een sleutel hoort bij precies één organisatie. Alle endpoints tonen en wijzigen alleen gegevens van die organisatie; een ID van een andere organisatie geeft 404.

Sleutels aanmaken en intrekken

OnderwerpHoe het werkt
WieAlleen de eigenaar of een beheerder van de organisatie
WaarInstellingen → API in Factora, na bevestiging van je wachtwoord
NaamVerplicht, max. 120 tekens; kies per koppeling een herkenbare naam
VervaldatumOptioneel; moet na vandaag liggen. Na die datum geeft de sleutel 401
Formaatfactora_ gevolgd door 64 tekens
OpslagFactora bewaart alleen een SHA-256-hash; de sleutel zelf zie je één keer
IntrekkenDirect actief via dezelfde pagina; ook superbeheerders van Factora kunnen een gelekte sleutel intrekken
AuditAanmaken en intrekken worden vastgelegd in het auditlog, inclusief de eerste tekens van de sleutel
Laatst gebruiktElk geldig verzoek werkt last_used_at bij; zichtbaar in de instellingen en via GET /me

Wat een sleutel mag

Een API-sleutel vertegenwoordigt de organisatie zelf en heeft alle rechten binnen het pakket. Er zijn (nog) geen scopes per sleutel. Welke endpoints werken, bepaalt het pakket: een module die niet in het pakket zit, geeft 403 met package_feature_unavailable.

Wanneer een sleutel wordt geweigerd

StatusMeldingOorzaak
401API key ontbreekt. Gebruik Authorization: Bearer <api_key>.Geen Authorization-header
401Ongeldige of verlopen API key.Onbekend, ingetrokken of verlopen
402Rond eerst de eerste pakketbetaling af om de API te activeren.Organisatie nog niet geactiveerd
402Organisatie is geblokkeerd door een verlopen abonnement.Abonnement verlopen
403Organisatie is niet actief.Organisatie inactief of geblokkeerd
403Limietmelding met error.codePakket bevat de API niet

Veilig gebruik

  • Bewaar sleutels alleen server-side, versleuteld of in een secret manager.
  • Gebruik nooit een sleutel in een browser, mobiele app of andere code die gebruikers kunnen inzien.
  • Log geen volledige Authorization-headers.
  • Wissel sleutels periodiek: maak een nieuwe aan, zet je koppeling om en trek de oude in.
  • Vermoed je een lek? Trek de sleutel direct in en controleer het auditlog.

Lees ook