Authenticatie

API-sleutels#

Authorization: Bearer hrs_live_…

• Live en test. Een sleutel met hrs_live_ werkt in je echte organisatie. Een sleutel met hrs_test_ werkt in je sandbox, met fictieve medewerkers.
• Persoonlijk. Een sleutel handelt als de gebruiker die hem maakte, binnen één organisatie en met de gekozen rechten. Wat jij niet mag, mag de sleutel ook niet. De rollen komen bij elk verzoek uit je lidmaatschap: wie uit de organisatie verdwijnt, heeft direct een sleutel die niet meer werkt.
• Eén keer zichtbaar. Je ziet de sleutel alleen bij het maken; Agreli bewaart een SHA-256-hash. Kies eventueel een geldigheid van 1 tot 730 dagen.
• Wie wat mag maken. Testsleutels, en sleutels met onboardings:write, contracts:write of webhooks:manage, maakt alleen een eigenaar of manager.
• Geen cookies. De API kijkt alleen naar de Bearer-sleutel. Roep hem aan vanaf je server, nooit vanuit de browser.

Elk antwoord heeft de koppen X-Request-Id (noem die bij vragen), Agreli-Mode (live of test), Agreli-Version en de koppen van de snelheidslimiet.

Rechten (scopes)#

Een sleutel heeft één of meer rechten. Zonder het juiste recht krijg je 403 permission_error.

Goedkeuren via de API (approvals:write) gebeurt als de eigenaar van de sleutel. Vierogen blijft gelden: dezelfde persoon kan niet twee rollen vervullen, en de data_version moet gelijk zijn aan de versie die is gecontroleerd.

Goedkeuren en de verklaring dat het originele identiteitsbewijs is gezien, staan via de API standaard uit: dat hoort een mens te doen. Een eigenaar zet het aan bij Instellingen, API en webhooks; anders geeft de API 403 api_approvals_disabled. Alles wat via een sleutel gebeurt, staat met die sleutel in de tijdlijn van het dossier, ook het openen ervan.

Een sleutel van een lid dat beperkt is tot bepaalde vestigingen, ziet alleen de onboardings van die vestigingen.

Idempotency-Key#

Stuur bij schrijfacties (POST, PATCH en DELETE) een Idempotency-Key mee, bijvoorbeeld een UUID die je bij je eigen record bewaart.

• Hetzelfde verzoek met dezelfde sleutel geeft binnen 24 uur hetzelfde antwoord, met de kop Idempotent-Replayed: true.
• Dezelfde sleutel met een andere inhoud geeft 422 met code idempotency_conflict.
• Loopt het eerste verzoek nog, dan krijgt een herhaling 409 met code idempotency_in_progress. Probeer het na een paar seconden opnieuw: het werk wordt nooit twee keer gedaan.
• Alleen geslaagde antwoorden worden vastgelegd. Na een fout kun je dus gewoon opnieuw proberen, met dezelfde sleutel.
• Een sleutel is hooguit 200 tekens en geldt per API-sleutel en per werkgever. Een partner die dezelfde sleutel voor twee werkgevers gebruikt, krijgt dus nooit het antwoord van de ene bij de andere.

Versies#

De API heeft datumversies. De huidige is 2026-10-01.

• Een API-sleutel en een webhookadres onthouden de versie van het moment waarop je ze maakte. Een webhook komt altijd in de versie van het adres; api_version staat in elk bericht.
• Kies per verzoek een andere versie met de kop Agreli-Version: 2026-10-01. Een onbekende versie geeft 422 api_version_invalid. Het antwoord noemt de gebruikte versie in de kop Agreli-Version.
• Nieuwe velden, gebeurtenissen en endpoints komen er zonder nieuwe versie bij. Houd daar rekening mee: negeer velden die je niet kent.
• Alleen een wijziging die bestaande code breekt, zoals een veld dat verdwijnt of van betekenis verandert, krijgt een nieuwe versie. Een oude versie blijft daarna minstens 12 maanden werken, en we mailen je ruim van tevoren.

Werken namens werkgevers#

Een softwarepartner (API-partner) werkt voor meerdere werkgevers. Een partnersleutel hoort bij de partnerorganisatie; per verzoek kies je de werkgever met de kop Agreli-Organization:

curl https://app.agreli.nl/api/public/v1/onboardings \
  -H "Authorization: Bearer $AGRELI_API_KEY" \
  -H "Agreli-Organization: org_…"

• GET /v1/organizations geeft de werkgevers die jou uitdrukkelijk hebben toegelaten, met de rechten die ze gaven.
• Je rechten zijn de doorsnede van de rechten van je sleutel en wat de werkgever toestaat. Een partner kiest uit organization:read, onboardings:read, onboardings:write, integrations:read en webhooks:manage.
• Zonder de kop krijgt een partnersleutel 422 organization_required. Een werkgever die de partner niet (meer) toelaat, geeft 403.
• Je ziet en beheert bij een werkgever alleen de onboardings die via jouw sleutels liepen. Onboardings die de werkgever zelf (of een andere partner) startte, bestaan voor jou niet: die geven 404, ook in lijsten en in GET /v1/events.
• Webhooks en het logboek van een partner horen bij de partner zelf. organization_id in een webhook zegt van welke werkgever het bericht is.
• Een werkgeverssleutel heeft de kop niet nodig. Stuur je hem toch mee, dan moet het de eigen organisatie zijn.
• Testsleutels werken in de sandbox van de partner, een fictieve werkgever; daar is de kop niet nodig.

Een werkgever laat een partner toe via een uitnodiging per e-mail en kan dat altijd beëindigen. Daarna werkt de sleutel voor die werkgever direct niet meer. Live sleutels en werkgevers uitnodigen kan pas na productietoegang.

Sleutels roteren#

In het developer dashboard roteer je een sleutel zonder onderbreking:

• De nieuwe sleutel krijgt dezelfde naam, rechten, modus en eigenaar, en dezelfde looptijd als de oude, gerekend vanaf de rotatie.
• De oude sleutel blijft een overgangstermijn geldig: 0 tot 168 uur, standaard 24. Bij 0 uur is hij direct ingetrokken.
• Een eigenaar of manager kan ook de sleutels van anderen roteren of intrekken. Die blijven handelen als hun eigenaar.

Roteer zo: maak de nieuwe sleutel, zet hem in je configuratie, controleer dat verzoeken slagen en laat de oude verlopen.