HTTP API
API-sleutels, base URL en authenticatie voor de Tillor REST API
Laatst bijgewerkt op
De Tillor API is een REST API. Authenticeer met een API-sleutel en stuur de juiste headers bij elke request. API-sleutels zijn per account - één sleutel werkt voor alle organisaties waar je toegang toe hebt.
API-referentie en OpenAPI
- API-referentie - Elk endpoint met parameters en voorbeelden; probeer requests direct in de browser
- OpenAPI-specificatie - Volledige API-documentatie in JSON-formaat voor codegeneratie of import in Postman/Insomnia
API-sleutels
Aanmaken
API-sleutels maak je aan in de Tillor-app via het gebruikersmenu onder Account > API-sleutels (markering 1 = menu, markering 2 = API-sleutels in de screenshot). Je kunt ze ook via de API aanmaken met een ingelogde sessie (geen API-sleutel). Zie de OpenAPI-specificatie onder tag api-keys voor paden, request- en response-schema's.
De ruwe sleutel wordt eenmalig teruggegeven bij aanmaken of regenereren. Bewaar deze veilig; je kunt hem daarna niet meer ophalen.
Rechten beperken
Standaard kan een sleutel alles wat jij zelf mag, in elke organisatie waar je lid van bent. Zet in het sleutelvenster Beperken tot geselecteerde rechten aan en kies de rechten die de koppeling nodig heeft, bijvoorbeeld alleen facturen lezen. Een beperkte sleutel krijgt in elke organisatie de doorsnede van zijn rechten en jouw lidmaatschap daar: een sleutel kan nooit meer dan jij. Een aanroep buiten de gekozen rechten krijgt 403 Forbidden, net als een gebruiker zonder dat recht. Een wijziging van de rechten geldt binnen een minuut. Via de API: scopes (lijst van rechten-ids zoals invoices:read, of null voor alles) bij aanmaken en bijwerken van een sleutel.
Gebruik
Stuur de API-sleutel in de x-api-key header:
x-api-key: tkn_xxxSleutels gebruiken het tkn_-voorvoegsel. Bij organisatie-endpoints staat het organisatie-ID in het pad (/orgs/org_abc123/...); een aparte header is niet nodig.
Rate limits
- Standaard: 5000 requests per 60 seconden per sleutel
- Bij overschrijding:
429 Too Many RequestsmetRetry-After - Elke API-sleutelresponse bevat IETF
RateLimit-*headers:
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60RateLimit-Reset is het aantal seconden tot het huidige venster opnieuw begint. Browser-clients kunnen deze headers lezen via CORS (Access-Control-Expose-Headers).
Beveiliging
Let op
- Nooit API-sleutels blootstellen in client-side code of publieke repositories
- Regenerereer sleutels periodiek via Regenereren in de app (OpenAPI:
POST /api/api-keys/:id/renew) - Verwijder ongebruikte sleutels met
DELETE /api/api-keys/:id
Base URL en organisatie-context
Base URL: https://tillor.eu (of je deployment-URL; OpenAPI noemt {APP_URL}/api)
Organisatie-paden: Voeg het organisatie-ID toe in het pad:
/api/orgs/:orgId/...Voorbeeld:
GET https://tillor.eu/api/orgs/org_abc123/customersVereiste header voor organisatie-endpoints: x-api-key: tkn_xxx. Het organisatie-ID staat in het pad.
Voorbeeld: cURL
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
-H "x-api-key: tkn_xxx" \
-H "Content-Type: application/json"Integraties (marketplace)
Organisatie-integraties (voorheen "apps" in de API) gebruiken één resource per type onder /api/orgs/:orgId/integrations/{integrationType}. Vereiste permissies zijn organization:integrations:read en organization:integrations:write (vervangt organization:apps:*).
| Method | Pad | Beschrijving |
|---|---|---|
| GET | /integrations/{integrationType} | Status (installed, available) en redacted settings |
| POST | /integrations/{integrationType} | Installeren (optioneel settings in body; OAuth kan redirectUrl teruggeven) |
| PUT | /integrations/{integrationType} | Instellingen bijwerken (settings in body) |
| DELETE | /integrations/{integrationType} | Deinstalleren |
Bij GET en na PUT bevat settings alleen publieke velden plus per geheim veld { configured: true }. Wachtwoorden, API-keys en OAuth-tokens komen niet terug. Laat geheime velden leeg bij PUT om de bestaande waarde te behouden.
Zie de OpenAPI-specificatie (tag integrations) voor exacte schema's.
Gerelateerd
- API-referentie - Elk endpoint, uit te proberen in de browser
- OpenAPI - API-specificatie (JSON)
- MCP - Cursor, Claude, ChatGPT of Gemini koppelen via OAuth
- Externe notificaties - Registreer e-mails die je eigen systeem verstuurde
- Webhooks - Ontvang events via HTTP POST
- Inkomende webhook van een automatisering - Start een automatisering met een POST, zonder API-sleutel
- SSE - Stream events via Server-Sent Events
- Voorbeelden - Code- en payload-voorbeelden