API-sleutels

Wil je Bookordo koppelen aan je eigen software of aan een automatiseringstool zoals Zapier, dan gebruik je de tenant-API. Onder API-sleutels in het beheer maak je sleutels aan waarmee externe systemen veilig toegang krijgen tot jouw gegevens onder /api/tenant-api/v1/*.

Een sleutel aanmaken

1. Ga naar API-sleutels en klik op Nieuwe sleutel.
2. Geef de sleutel een herkenbare Naam, bijvoorbeeld "Zapier integratie".
3. Kies de Scopes: wat deze sleutel precies mag. Er zijn lees-scopes (onder andere Werkbonnen lezen, Medewerkers lezen, Diensttypen lezen, Werkstatussen lezen, Vrije dagen lezen, Materialen lezen, Webhooks lezen, CSAT lezen, Event-stream lezen) en schrijf-scopes (onder andere Werkbonnen wijzigen, Medewerkers wijzigen, Werkstatussen wijzigen, Diensttypen wijzigen, Vrije dagen wijzigen, Materialen wijzigen, Webhooks beheren). Kies minimaal één scope en geef nooit meer rechten dan de koppeling nodig heeft.
4. Vink alleen in bijzondere gevallen Audit per call aan: dat schrijft extra logregels per request en is bedoeld voor forensisch gebruik.
5. Klik op Aanmaken. Het venster Sleutel aangemaakt toont nu eenmalig de volledige sleutelwaarde met de waarschuwing "Kopieer de sleutel nu. Hij wordt later niet meer getoond." Kopieer hem met Kopieer en bewaar hem in een wachtwoordkluis. Klik daarna op Klaar.

De sleutellijst lezen

Per sleutel zie je in de lijst:

• de naam en het prefix (de eerste tekens van de sleutel, zodat je hem kunt herkennen zonder de volledige waarde);
• de toegekende scopes als badges, en eventueel het label "audit per call";
• het laatste gebruik: "Laatst gebruikt [datum en tijd] vanaf [IP-adres]" of "Nog niet gebruikt".

Een sleutel intrekken

Klik op Intrekken bij de sleutel en vul optioneel een reden in; die wordt gelogd. Intrekken werkt per direct: elk systeem dat deze sleutel gebruikt verliest meteen de toegang. Intrekken is definitief; maak zo nodig een nieuwe sleutel aan.

Instellingen die hierop ingrijpen

• Auditlogboek: het aanmaken en intrekken van sleutels wordt gelogd als api_key_created en api_key_revoked, zie Auditlogboek.
• Webhooks: met de webhook-scopes beheert een extern systeem de webhooks die Bookordo bij gebeurtenissen aanroept.
• Gebruikers: alleen beheerders met toegang tot de instellingen kunnen sleutels beheren, zie Gebruikers en rollen.

Veelgestelde vragen en problemen

Ik ben de sleutelwaarde kwijt. Kan ik hem opnieuw bekijken? Nee. De volledige sleutel wordt om veiligheidsredenen maar één keer getoond, direct na het aanmaken. Trek de oude sleutel in en maak een nieuwe aan.

Welke sleutel gebruikt mijn koppeling ook alweer? Kijk naar het prefix in de lijst en vergelijk dat met de eerste tekens van de sleutel in je externe systeem. De regel "Laatst gebruikt ... vanaf ..." helpt ook: daar zie je wanneer en vanaf welk IP-adres de sleutel voor het laatst is gebruikt.

Mijn koppeling krijgt ineens foutmeldingen over rechten. Controleer of de sleutel alle benodigde scopes heeft. Een sleutel met alleen "Werkbonnen lezen" kan bijvoorbeeld geen werkbonnen wijzigen. Scopes van een bestaande sleutel wijzig je niet achteraf: maak een nieuwe sleutel met de juiste scopes en trek de oude in.

Is er een aparte proef- of testomgeving? Nee, sleutels werken op je echte gegevens. Test schrijf-scopes daarom voorzichtig, bijvoorbeeld eerst met een sleutel die alleen lees-scopes heeft.

Hoeveel sleutels kan ik aanmaken? Zoveel als je nodig hebt. Maak per koppeling een eigen sleutel aan; dan kun je één koppeling intrekken zonder de andere te raken en zie je per sleutel het laatste gebruik.