Automatisering & API Beschikbaar
REST API & API-sleutels
De API is geen laag naast het product, hij is het product. De webapp gebruikt hem, de MCP-server proxyt ernaartoe en jouw script spreekt precies dezelfde endpoints aan.
Wat je nodig hebt
- Je eigen tenant-hostname over HTTPS: het geverifieerde eigen domein, of <slug>.<basisdomein>
- Het recht apikeys.personal.manage voor een persoonlijke sleutel, of apikeys.service_account.manage voor een service-account
- Een beeld van welke rechten de koppeling nodig heeft: scopes komen uit dezelfde rechtencatalogus als rollen
- Voor de interactieve referentie: SCHAKL_API_DOCS_ENABLED mag niet op false staan (standaard staat hij aan)
Zo koppel je het
- 1 Open de referentie op
https://<je-host>/api/docs(Swagger UI) ofhttps://<je-host>/api/redoc. Het document zelf staat op/api/openapi.json. Let op het pad: alles staat onder/api/, want dat is de enige prefix die de edge naar de API-service stuurt. - 2 Maak een persoonlijke sleutel aan: Instellingen → Mijn account, sectie API-sleutels. Vul Naam in (bijvoorbeeld
n8n-automatisering), kies eventueel een datum bij Verloopt op en vink onder Scopes aan wat het script nodig heeft. Minstens één scope is verplicht. - 3 Of maak een sleutel die niemands account nodig heeft: Instellingen → Service-accounts → Service-account toevoegen, daarna Nieuwe sleutel. Zo'n sleutel draagt precies zijn eigen scopes en blijft werken als de aanmaker vertrekt.
- 4 Kopieer de sleutel meteen:
schakl_<prefix>_<secret>. Hij wordt één keer getoond, want alleen een hash van het geheim wordt bewaard; daarna geeft de API nog slechtsschakl_<prefix>_********terug. - 5 Stuur hem mee als
Authorization: Bearer schakl_…of alsX-API-Key: schakl_…, altijd naar je eigen tenant-hostname. - 6 Voor n8n: één HTTP Request-node per endpoint, met de sleutel als header-credential. Er is geen aparte n8n-koppeling; het is dezelfde API die de app zelf gebruikt.
- 7 Bouw je een echte client, genereer hem dan uit
/api/openapi.json. De webapp doet precies dat, metopenapi-typescript, zodat een endpoint dat verandert een typefout oplevert in plaats van een verrassing.
Persoonlijke sleutel of service-account
Een persoonlijke sleutel hoort bij jou en wordt bij elk verzoek afgetopt op je actuele rechten: word je gedegradeerd, dan krimpt de sleutel mee. Dat is precies wat je wil voor een script dat namens jou werkt, en precies wat je niet wil voor de koppeling waar het bureau op draait. Daarvoor is er het service-account: een gedeelde principal die niet aan een persoon hangt, met zijn eigen scopes, beheerd door een beheerder.
- Een sleutel hoort bij één organisatie; op een andere hostname wordt hij niet gevonden
- Ingetrokken, verlopen of onbekend antwoordt allemaal met dezelfde 401, zonder te bevestigen dat de sleutel bestaat
- Een vervaldatum mag maximaal 366 dagen vooruit; leeg laten betekent nooit verlopen, en intrekken is dan de noodrem
Waarom de referentie onder /api/ staat
De edge stuurt precies twee prefixen naar de API-service: /api/ en /mcp. Al het andere gaat naar de webapp. Op de standaardpaden van FastAPI (/docs, /redoc, /openapi.json) kwam je dus op de 404 van de webapp uit: de documentatie was niet uitgezet, ze was onbereikbaar. Nu staat ze onder de prefix die er wel komt, zonder aanpassing aan je edge. Wil je hem helemaal niet serveren: zet SCHAKL_API_DOCS_ENABLED op false. Het document wordt intern gewoon nog opgebouwd, dus de getypte client en de MCP-toolset blijven werken.
De vorm van de API
Meervoudige zelfstandige naamwoorden onder /api/v1/<module>/<resource>. Lijst-endpoints nemen limit en offset, en met count=false sla je het totaal over als je het niet nodig hebt. Fouten komen in één envelop terug, { error: { code, message, fields? } }, waarbij message een i18n-sleutel is en dus geen zin die je aan je gebruiker moet laten zien. Elke module die aanstaat breidt dezelfde API en dezelfde spec uit.
Rechten
Geef deze rechten aan de rol die deze koppeling beheert (Instellingen → Rollen). Standaard alleen voor beheerders, en nooit voor de rol client.
-
apikeys.personal.manageEigen API-sleutels beheren: zelf een sleutel aanmaken en intrekken. Standaard voor beheerder en medewerker, want zo'n sleutel kan nooit meer dan de eigenaar zelf. -
apikeys.service_account.manageServiceaccounts beheren: gedeelde sleutels die aan geen enkele medewerker hangen. Standaard alleen voor beheerders.
Wat het bewust niet doet
- 600 verzoeken per minuut per sleutel. Genoeg voor automatisering, en een vaste grens onder een gelekte sleutel.
- Het geheim wordt niet bewaard, alleen de hash ervan. Kwijt is kwijt: intrekken en een nieuwe aanmaken.
- Een sleutel geeft nooit meer dan zijn scopes, en een persoonlijke sleutel nooit meer dan zijn eigenaar op dat moment mag. Rechten toekennen doe je in Instellingen → Rollen, niet op de sleutel.
- De kolom Laatst gebruikt loopt achter: die wordt buiten het verzoek om bijgewerkt, zodat een API-aanroep er niet op wacht.
- Uitgaande event-webhooks bestaan nog niet. Reageren op een wijziging betekent vandaag pollen, of een automatiseringsregel met de actie Webhook aanroepen.
- Bulk-export via /impex vraagt een eigen recht (impex.export) bovenop het leesrecht van de entiteit; een sleutel die klanten mag lezen, mag daarmee nog geen klantenlijst downloaden.
Waar je het vindt Instellingen → Mijn account, sectie API-sleutels voor persoonlijke sleutels; Instellingen → Service-accounts voor koppelingen. De referentie zelf staat op https://<je-host>/api/docs.
Lees de handleiding