Authenticatie
Hoe je met een API-sleutel authenticeert, welke scopes er zijn en hoe je sleutels veilig beheert.
De Authorization-header
Stuur bij elk verzoek je sleutel mee als Bearer-token:
GET /api/v1/me HTTP/1.1
Host: app.klantly.com
Authorization: Bearer kly_4fZ2mQ8v...Zonder geldige sleutel volgt 401 met de code unauthenticated of invalid_api_key.
Hoe een sleutel eruitziet
Een sleutel begint altijd met kly_, gevolgd door 49 tekens. Aan het voorvoegsel is een uitgelekte sleutel te herkennen, bijvoorbeeld door secret scanning op GitHub. De laatste tekens vormen een controlesom: een sleutel met een tikfout wordt direct afgewezen.
Klantly bewaart alleen een onomkeerbare vingerafdruk van de sleutel. Niemand kan hem later nog tonen, ook Klantly niet. Ben je hem kwijt? Maak dan een nieuwe aan.
Scopes
Een sleutel kan alleen wat zijn scopes toestaan. Kies bij het aanmaken Alleen lezen, Volledige toegang of een eigen selectie.
| Scope | Omschrijving |
|---|---|
customers.read | Klanten en leads lezen |
customers.write | Klanten en leads aanmaken en wijzigen |
deals.read | Deals en pipelinefasen lezen |
deals.write | Deals aanmaken, wijzigen, verplaatsen en archiveren |
appointments.read | Afspraken (met naam, e-mail en telefoon van de klant), afspraaktypes en beschikbaarheid lezen |
appointments.write | Afspraken aanmaken, wijzigen, bevestigen, annuleren en afronden (automations van het bedrijf lopen mee) |
appointments.delete | Afspraken verwijderen |
appointments.send | Afspraakberichten naar klanten mailen |
tasks.read | Taken, borden en reacties lezen |
tasks.write | Taken aanmaken, wijzigen, verplaatsen en afronden, en reacties plaatsen |
tasks.delete | Taken verwijderen |
work_orders.read | Werkbonnen lezen, met naam, adres en contactgegevens van de klant |
work_orders.write | Werkbonnen aanmaken en wijzigen, en de status aanpassen (afronden kan een reviewverzoek sturen) |
work_orders.delete | Werkbonnen verwijderen |
services.read | Serviceverzoeken lezen, met naam, adres en contactgegevens van de klant |
services.write | Serviceverzoeken aanmaken en wijzigen, de status aanpassen en foto's toevoegen |
services.delete | Serviceverzoeken verwijderen |
quotes.read | Offertes lezen, met regels, bedragen en de klantgegevens erop |
quotes.write | Offertes aanmaken en wijzigen (alleen concepten), en accepteren of afwijzen namens de klant |
quotes.delete | Offertes verwijderen |
quotes.send | Offertes naar klanten mailen |
invoices.read | Facturen lezen, met regels, bedragen, betalingen en de klantgegevens erop |
invoices.write | Facturen aanmaken (ook van een offerte) en wijzigen (alleen concepten), annuleren, betalingen registreren, crediteren en een terugbetaling vastleggen |
invoices.delete | Concept-facturen verwijderen |
invoices.send | Facturen naar klanten mailen en de betaallink voor de klant ophalen |
orders.read | Webshopbestellingen lezen, met regels, adressen en de contactgegevens van de klant |
orders.write | De status van webshopbestellingen wijzigen (de klant krijgt dan mail), track and trace invullen en notities plaatsen |
messages.read | Gesprekken en berichten lezen uit de inbox |
messages.send | Berichten naar klanten sturen en gesprekken sluiten |
reviews.read | Reviews en reviewverzoeken lezen |
reviews.write | Reviewverzoeken naar klanten sturen (een review zelf aanmaken kan niet) |
meta_copilot.read | De stand en de meldingen van de Meta co-pilot lezen |
meta_copilot.write | De Meta co-pilot met de noodstop stilzetten, kansen laten oppakken of afwijzen en voorstellen goedkeuren of afwijzen (het mandaat instellen kan alleen in het scherm) |
users.read | Gebruikers van het bedrijf lezen |
company.read | Bedrijfsgegevens lezen |
webhooks.manage | Webhook-endpoints beheren |
events.read | Events ophalen |
Een sleutel krijgt nooit meer rechten dan de beheerder die hem aanmaakt, bewerkt of vernieuwt: rechten die je zelf niet hebt, kun je niet toekennen. Ontbreekt een scope, dan volgt 403 met de code insufficient_scope, en in required_scope staat welke scope nodig is.
Een scope alleen is soms niet genoeg: hoort het endpoint bij een functie die niet in het pakket van je bedrijf zit — bijvoorbeeld het pipelinebord, offertes, facturen, werkbonnen, de webshop of reviews — dan volgt 403 met de code feature_not_available, en het veld feature noemt welke functie ontbreekt. Scopes die je bedrijf niet kan gebruiken, kun je ook niet aan een sleutel geven.
Vervaldatum, IP-allowlist en vernieuwen
- Vervaldatum: 30, 90 of 365 dagen, of onbeperkt. Standaard is 365 dagen. In Klantly zie je welke sleutels binnenkort verlopen.
- IP-allowlist: beperk een sleutel tot de IP-adressen of reeksen (CIDR) van je server.
- Vernieuwen: je krijgt een nieuwe sleutel met dezelfde instellingen. De oude blijft naar keuze nog 1 uur, 24 uur of 7 dagen geldig, zodat je koppeling zonder onderbreking kan overstappen. Is de sleutel uitgelekt, kies dan geen overlap: de oude werkt dan meteen niet meer.
Als een sleutel is uitgelekt
- Trek de sleutel direct in onder Integraties → API. Hij werkt meteen niet meer.
- Maak een nieuwe sleutel aan en zet die in je koppeling.
- Bekijk in het tabblad Gebruik welke verzoeken er met de oude sleutel zijn gedaan.
Veilig bewaren
- Bewaar sleutels in een omgevingsvariabele of een secrets manager, nooit in je broncode.
- Gebruik een sleutel alleen op een server. De API staat geen verzoeken vanuit een browser toe (geen CORS).
- Geef elke koppeling een eigen sleutel met alleen de scopes die hij nodig heeft.
Laatst bijgewerkt op 18 september 2026