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 Playground en OpenAPI
- API Playground - Probeer endpoints direct in de browser met je API-sleutel
- 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.
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 Playground - Endpoints uitproberen 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