Elk verzoek aan de REST API stuurt een API-sleutel mee. De sleutel hoort bij één werkruimte en bepaalt wat je mag: lezen, schrijven of allebei.
De header
Stuur de sleutel mee in de header Authorization, met het woord Bearer ervoor:
Authorization: Bearer LF_LIVE_SLEUTEL
Het woord Bearer is niet hoofdlettergevoelig en spaties rond de sleutel worden weggehaald. Zonder header, met een ander schema of met een lege sleutel krijg je een 401.
Sleutelvorm
Een API-sleutel begint met lf_live_, gevolgd door 43 willekeurige tekens. LeadForge bewaart de sleutel zelf niet, alleen een hash ervan en het begin (lf_live_ plus acht tekens) om hem te herkennen. De volledige sleutel zie je daarom maar één keer, bij het aanmaken. Bewaar hem meteen op een veilige plek, bijvoorbeeld in de geheimenkluis van je server.
Rechten
Een sleutel heeft een of beide van deze rechten:
| Recht | Wat het toestaat |
|---|---|
read | Alle GET-verzoeken. |
write | POST /api/v1/conversations/{id}/reply, een antwoord klaarzetten. |
Welke rechten je sleutel heeft, zie je in het veld scopes van GET /api/v1/me.
Let op
write kan geen GET doen. Wil je lezen en een antwoord klaarzetten, dan heeft de sleutel beide rechten nodig.Eén werkruimte per sleutel
Een sleutel hoort bij precies één werkruimte. Elk antwoord gaat alleen over die werkruimte. Vraag je een lead of gesprek op met een id uit een andere werkruimte, dan krijg je een 404, net alsof het niet bestaat. Werk je voor meer werkruimtes, gebruik dan per werkruimte een eigen sleutel.
Wie een sleutel krijgt
Een API-sleutel wordt aangemaakt voor één werkruimte, en alleen een eigenaar of beheerder van die werkruimte mag dat. Hetzelfde geldt voor intrekken.
- Een sleutel heeft een naam, tot 80 tekens. Kies een naam waaraan je ziet waar hij gebruikt wordt, bijvoorbeeld de naam van je CRM.
- Zonder recht erbij krijgt een sleutel alleen
read. - Het aanmaken en het intrekken van een sleutel worden vastgelegd.
- Een ingetrokken sleutel geeft meteen een 401.
Goed om te weten
lf_ext_) en een MCP-sleutel (lf_mcp_) werken niet op de REST API. Daar geeft elke aanroep een 401.Volgorde van controles
De API controleert elk verzoek in deze volgorde. De eerste controle die faalt bepaalt het antwoord.
- De sleutel: ontbreekt hij, is hij onbekend of ingetrokken, of is het geen API-sleutel, dan volgt 401.
- De rechten: heeft de sleutel het gevraagde recht niet, dan volgt 403.
- De werkruimte: hoort de sleutel niet bij precies één werkruimte, dan volgt 403.
- De limiet: meer dan 120 verzoeken per minuut geeft 429.
- Pas daarna kijkt de API naar het verzoek zelf. Bij de reply is dat eerst de body en dan het id in het pad.
| Status | Code | Wanneer |
|---|---|---|
| 401 | unauthorized | Geen geldige API-sleutel. Stuur 'Authorization: Bearer lf_live_...' mee. |
| 403 | forbidden | Deze sleutel heeft geen 'read'-rechten. (of 'write') |
| 403 | forbidden | Deze sleutel hoort niet bij precies één werkruimte. |
| 429 | rate_limited | Te veel verzoeken. Maximaal 120 per minuut. |