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 versleutelde 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 |
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.
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.
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 15 september 2026