Authenticatie en API-sleutels

Elke aanroep van de API draagt een API-sleutel. Een beheerder maakt de sleutel in Schedulinq, kiest wat hij mag, en geeft hem aan wie de koppeling bouwt. Deze handleiding behandelt beide helften: de sleutel maken, en hem meesturen.

Een sleutel maken

1. Open Integraties → API

   Alleen beheerders zien deze pagina. Druk onder Sleutels op Nieuwe sleutel.

2. Vul de sleutel in

   Geef hem een Naam — het systeem dat hem gebruikt, zoals "CRM productie". Vink onder Wat mag deze sleutel? de rechten aan die hij nodig heeft (hieronder). Kies bij Teamleden uitnodigen ook de Rollen die deze sleutel mag toewijzen. Kies onder Verloopt de sleutel? een datum bij Geldig tot en met, of geen.

3. Kopieer de sleutel nu

   Na Sleutel aanmaken zie je de sleutel één keer. Kopieer hem en bewaar hem op een veilige plek, zoals de geheimenopslag van je server. Je ziet hem hierna niet meer.

Een organisatie heeft hoogstens vijf actieve sleutels. Elke beheerder krijgt een e-mail zodra er een sleutel wordt aangemaakt of ingetrokken.

Meesturen

Stuur de sleutel mee in de header Authorization, als Bearer-token:

curl https://api.schedulinq.com/api/v1/services \
  -H "Authorization: Bearer $SCHEDULINQ_API_KEY"

• Altijd in de header, nooit in een querystring.
• Een sleutel is sq_live_ gevolgd door 64 hexadecimale tekens in kleine letters. Aan het voorvoegsel sq_live_ herkennen secret-scanners een sleutel die in een repository is beland.
• De voorbeelden in dit hoofdstuk gebruiken sq_live_EXAMPLE-NOT-A-REAL-KEY. Dat is geen sleutel en werkt nooit.

Rechten (scopes)

Een sleutel mag alleen wat zijn rechten toestaan. Elk endpoint vraagt precies één recht; de referentie noemt het.

users:read

Je teamleden lezen en de openstaande uitnodigingen voor nieuwe, met hun status, agendakoppeling en eigen velden. In het dashboard: Teamleden bekijken.

Endpoints: GET /api/v1/users

users:write

Teamleden uitnodigen, en de rollen opvragen die deze sleutel ze mag geven. In het dashboard: Teamleden uitnodigen.

• De rollen die de sleutel mag toewijzen, kies je bij het maken van de sleutel; minstens één is verplicht.
• Beheerder is nooit toe te wijzen.
• Een rol die sindsdien is verwijderd, valt uit de set van de sleutel.
• GET /api/v1/roles noemt de rollen die de sleutel mag toewijzen.

Endpoints: POST /api/v1/users, POST /api/v1/users/invitations/{id}/resend, GET /api/v1/roles

services:read

Je actieve diensten lezen en welke teamleden ze doen. In het dashboard: Diensten bekijken.

Endpoints: GET /api/v1/services

appointments:read

Afspraken lezen, met hun kenmerken en zonder contactgegevens van klanten. In het dashboard: Afspraken bekijken.

Endpoints: GET /api/v1/appointments, GET /api/v1/appointments/{id}

invitations:read

De uitnodigingen om te boeken lezen, met hun status. In het dashboard: Uitnodigingen bekijken.

Endpoints: GET /api/v1/invitations, GET /api/v1/invitations/{id}

invitations:write

Een klant een uitnodiging sturen om een afspraak te boeken. In het dashboard: Uitnodigingen versturen.

Endpoints: POST /api/v1/invitations

planning_links:write

Een link maken die de planner opent voor een klant uit je CRM. In het dashboard: Planner openen.

Endpoints: POST /api/v1/planning-links

Eén sleutel per systeem, alleen de rechten die het gebruikt

Geef elk systeem dat de API aanroept een eigen sleutel, met alleen de rechten die het gebruikt. Zet users:write alleen op de sleutel van het systeem dat teamleden aanmaakt, en geef die sleutel alleen de rollen die het mag uitdelen. Een sleutel die uitlekt, kan dan niet meer dan dat ene systeem nodig had.

Wat een sleutel niet kan

Een sleutel werkt alleen op /api/v1, nooit op het dashboard. Sleutels en webhooks zelf beheert alleen een beheerder, in het dashboard; geen sleutel kan een andere sleutel maken, wijzigen of intrekken.

Intrekken, verlopen en vervangen

• Een ingetrokken of verlopen sleutel wordt bij zijn volgende verzoek geweigerd met een 401.
• Het verlopen is een datum: de laatste geldige dag van de sleutel, in de tijdzone van je organisatie, hoogstens vijf jaar vooruit.
• De sleutelpagina laat zien wanneer elke sleutel voor het laatst is gebruikt, en vanaf welk IP-adres.
• Een sleutel is van de organisatie, niet van de beheerder die hem maakte: hij blijft werken als die beheerder vertrekt. Trek de sleutels van een vertrekkende beheerder in.

Een sleutel vervangen:

1. Maak de volgende sleutel en zet hem in gebruik

   De grens van vijf sleutels laat ruimte voor de oude en de nieuwe naast elkaar.

2. Laat herhaalpogingen op de oude sleutel afronden

   Een Idempotency-Key hoort bij de API-sleutel waarmee hij is verstuurd, dus een herhaling met de nieuwe sleutel wordt opnieuw uitgevoerd in plaats van herhaald. Zie Idempotentie.

3. Trek de oude sleutel in

   Onder Integraties → API, Intrekken. Alles wat hem nog gebruikt, stopt meteen.

Waar een sleutel nooit mag staan

Niet in browsercode, niet in een URL, niet in een repository en niet in een logregel. Log de header Authorization nooit. Lekt een sleutel toch uit, trek hem dan meteen in en maak een nieuwe.

401, 403 en 429

• Een 401 betekent dat de sleutel ontbreekt, ongeldig, ingetrokken of verlopen is. De code zegt welke: errors.api.apiKeyMissing, errors.api.apiKeyInvalid, errors.api.apiKeyRevoked of errors.api.apiKeyExpired.
• Een 403 errors.api.insufficientScope noemt het ontbrekende recht in requiredScope.
• Te veel mislukte pogingen vanaf één adres geven een 429 errors.api.tooManyFailedAuthentications.

Elke code staat uitgelegd onder Foutmeldingen.

Veelgestelde vragen

Ik ben een sleutel kwijt. Kan ik hem opnieuw zien?

Nee: een sleutel is alleen te zien op het moment dat hij wordt gemaakt. Maak een nieuwe, zet hem in gebruik, en trek de oude in.

Kan een teamlid dat geen beheerder is sleutels beheren?

Nee. Een sleutel handelt voor de hele organisatie, dus alleen beheerders kunnen sleutels maken, zien of intrekken.