API-sleutels en webhooks

Andere systemen kunnen op twee manieren met je organisatie werken: met een API-sleutel lezen en schrijven ze zelf records en starten ze automatisaties; met een webhook laat een andere dienst kvyk.ai weten dat er iets gebeurd is, en een automatisatie neemt het vanaf daar over.

API-sleutels

Met een API-sleutel gebruikt een ander systeem, zoals je webshop of je boekhoudpakket, de API van je organisatie in één stage. Elke sleutel hoort bij een machinelid: een lid van je organisatie met een naam en zonder e-mailadres, dat zich nooit aanmeldt en alleen via zijn sleutels werkt. Het systeem leest en schrijft records als dat lid, met de datarollen van het lid, en start automatisaties die vanuit andere systemen gestart mogen worden. Meer kan het niet. Records die het toevoegt, zijn van het machinelid, en de geschiedenis toont de naam van het lid.

Open Technisch → Sleutels en geheimen in de zijbalk: je sleutels staan onder Sleutels voor je API. Alleen Administrators zien die lijst. Ze toont elke sleutel met zijn Machinelid, het begin van de sleutel, de stage, wanneer hij Gemaakt is en door wie, wanneer hij Laatst gebruikt is en wanneer hij Verloopt.

Een sleutel maken

1. Kies API-sleutel maken.
2. Kies onder Voor Een nieuw machinelid, of Een bestaand machinelid om een lid dat je eerder maakte een sleutel te geven voor zijn andere omgeving. Vul voor een nieuw lid in:
   • Naam: welk systeem hem gebruikt, zoals Stock sync.
   • Datarollen: wat het mag doen. Geef het er minstens één; elke datarol kan, ook Volledige toegang, maar niet Niet aangemeld.
3. Kies de Omgeving: Preview of Live. Een sleutel bereikt alleen de gegevens van die stage.
4. Kies wanneer hij Verloopt: over 30 dagen, 90 dagen, 1 jaar of Op een datum. Een sleutel verloopt altijd.
5. Kies API-sleutel maken.

De sleutel wordt één keer getoond, onder Kopieer deze sleutel nu. Kopieer hem en bewaar hem waar het systeem dat hem gebruikt zijn geheimen bewaart: kvyk.ai kan hem niet opnieuw tonen. Ben je hem kwijt, maak dan een nieuwe sleutel voor hetzelfde lid.

Het systeem stuurt de sleutel mee met elk verzoek, als Authorization: Bearer <de sleutel>.

Een machinelid heeft één sleutel voor Preview en één voor Live. Een nieuwe sleutel voor een lid in een omgeving vervangt de sleutel die het daar had: de oude werkt meteen niet meer. Maak een machinelid per systeem, zodat je er een kunt stoppen zonder de andere. Een organisatie kan tot 50 sleutels hebben.

Het machinelid

Een machinelid staat bij Personen, gemarkeerd als Machinelid. Open het om zijn datarollen of zijn afdeling te wijzigen, zoals bij iedereen. Het blijft altijd een Member: het bouwt en beheert niets, en een machinelid kost niets.

Om een systeem voorgoed te stoppen, verwijder je zijn machinelid: zijn sleutels werken meteen niet meer, en je kiest wie zijn records overneemt.

Als een sleutel verloopt

Een sleutel die binnen 14 dagen verloopt, staat in de lijst als Verloopt binnenkort, en een sleutel voorbij zijn dag als Verlopen; de pagina zegt hoeveel het er zijn. Elke Administrator hoort het op het dashboard en per e-mail, in de eigen taal: 14 dagen vooraf, een dag vooraf en zodra hij verlopen is, elk één keer. De melding opent de API-sleutels.

Een verlopen sleutel werkt niet meer: een systeem dat hem nog stuurt, wordt geweigerd, met een bericht dat de sleutel verlopen is en op welke dag. Wil je een systeem laten doorwerken, maak dan vóór die dag een nieuwe sleutel voor zijn machinelid op die stage, en zet de nieuwe sleutel in het systeem. Is een sleutel ingetrokken of vervangen, dan hoort niemand er nog iets over.

Een app openen met een sleutel

Een systeem dat een van je apps in een browser opent, zoals een testrobot of een scherm aan de muur, kan zich aanmelden met zijn sleutel. Het stuurt de sleutel als Authorization: Bearer <de sleutel> wanneer het het adres van de app opent; de app opent dan als het machinelid en blijft een kwartier aangemeld, waarna de sleutel opnieuw wordt gecontroleerd. Dat lukt alleen als het machinelid de app mag openen: voeg het, of een van zijn datarollen, toe aan het publiek van de app. Een sleutel opent alleen de apps van zijn eigen stage.

Voor je een veld hernoemt of verwijdert

Een systeem met een sleutel gebruikt de namen van je entiteiten, velden en koppelingen. Er een hernoemen of verwijderen op Live breekt het systeem tot het ook aangepast is. Als je zo’n wijziging publiceert terwijl een sleutel voor Live werkt, waarschuwt kvyk.ai je met de sleutels en wanneer elk laatst gebruikt werd, en vraagt het nog eens; zie Wijzigingen publiceren en terugdraaien. Pas eerst het systeem aan, of voeg het nieuwe veld toe naast het oude en verwijder het oude zodra elk systeem het nieuwe gebruikt.

Een sleutel intrekken

Kies Intrekken naast een sleutel, en dan Ja, intrekken. Systemen die hem gebruiken, kunnen je organisatie meteen niet meer bereiken. Dit kan niet ongedaan worden gemaakt. Het machinelid blijft, en je kunt het een nieuwe sleutel geven.

Webhooks

Met een webhook start een andere dienst een automatisatie door een webadres aan te roepen, bijvoorbeeld Mollie als er een betaling binnenkomt. De kolom Start op Automatisaties zegt dan Vanuit een andere dienst, en het eerste vak toont het adres waarop ze luistert, zoals /v1/hooks/mollie.

Zodat niemand anders haar kan starten, heeft elke webhook per stage een eigen geheim. Je maakt het geheim met de bewerking Make a new secret for a webhook automation in de groep Automations van je API-referentie: een Administrator of een Builder roept ze aan voor Live of Preview, en het antwoord bevat het geheim en het volledige adres voor de andere dienst. Het wordt maar die ene keer gegeven. Een nieuw geheim maken zet het oude meteen buiten werking.

Stel het adres dan in bij de andere dienst. De dienst bewijst op een van twee manieren dat de aanroep echt is, zoals het eerste vak van de automatisatie zegt:

• Met de handtekening. De dienst ondertekent elke aanroep met het geheim, in de header X-Kvyk-Signature: sha256=<handtekening>, een HMAC-SHA256 van de inhoud van de aanroep.
• Met het geheim in het adres. Voor diensten die niet kunnen ondertekenen, zoals Mollie, is het geheim een deel van het adres dat je de dienst geeft.

Een aanroep die niet goed ondertekend is, wordt geweigerd. Een goede krijgt meteen antwoord, en de automatisatie loopt in de stage van het geheim. Test de automatisatie eerst in Preview met een testrun, met Een voorbeeldbericht, als JSON zoals de dienst dat stuurt.