HTTP API
API keys, base URL and authentication for the Tillor REST API
Last updated on
The Tillor API is a REST API. Authenticate with an API key and send the right headers with every request. API keys are per account - one key works for all organisations you have access to.
API reference and OpenAPI
- API reference - Every endpoint with parameters and examples; try requests directly in the browser
- OpenAPI specification - Full API documentation in JSON format for code generation or import into Postman/Insomnia
API keys
Create
You create API keys in the Tillor app via the user menu under Account > API Keys (marker 1 = menu, marker 2 = API Keys in the screenshot). You can also create them through the API with a logged-in session (no API key). See the OpenAPI specification under tag api-keys for paths, request and response schemas.
The raw key is returned once on creation or regeneration. Store it safely; you cannot retrieve it afterwards.
Restrict permissions
By default a key can do everything you can do yourself, in every organisation you are a member of. In the key window, turn on Limit to selected permissions and choose the permissions the integration needs, for example only reading invoices. A restricted key gets, in each organisation, the intersection of its permissions and your membership there: a key can never do more than you. A call outside the chosen permissions gets 403 Forbidden, just like a user without that permission. A change to the permissions applies within a minute. Through the API: scopes (list of permission IDs such as invoices:read, or null for everything) when creating and updating a key.
Usage
Send the API key in the x-api-key header:
x-api-key: tkn_xxxKeys use the tkn_ prefix. For organisation endpoints the organisation ID is in the path (/orgs/org_abc123/...); a separate header is not needed.
Rate limits
- Default: 5000 requests per 60 seconds per key
- When exceeded:
429 Too Many RequestswithRetry-After - Every API key response contains IETF
RateLimit-*headers:
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60RateLimit-Reset is the number of seconds until the current window starts again. Browser clients can read these headers via CORS (Access-Control-Expose-Headers).
Security
Note
- Never expose API keys in client-side code or public repositories
- Regenerate keys periodically via Regenerate in the app (OpenAPI:
POST /api/api-keys/:id/renew) - Delete unused keys with
DELETE /api/api-keys/:id
Base URL and organisation context
Base URL: https://tillor.eu (or your deployment URL; OpenAPI mentions {APP_URL}/api)
Organisation paths: Add the organisation ID to the path:
/api/orgs/:orgId/...Example:
GET https://tillor.eu/api/orgs/org_abc123/customersRequired header for organisation endpoints: x-api-key: tkn_xxx. The organisation ID is in the path.
Example: cURL
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
-H "x-api-key: tkn_xxx" \
-H "Content-Type: application/json"Integrations (marketplace)
Organisation integrations (formerly "apps" in the API) use one resource per type under /api/orgs/:orgId/integrations/{integrationType}. Required permissions are organization:integrations:read and organization:integrations:write (replaces organization:apps:*).
| Method | Path | Description |
|---|---|---|
| GET | /integrations/{integrationType} | Status (installed, available) and redacted settings |
| POST | /integrations/{integrationType} | Install (optional settings in body; OAuth can return redirectUrl) |
| PUT | /integrations/{integrationType} | Update settings (settings in body) |
| DELETE | /integrations/{integrationType} | Uninstall |
On GET and after PUT, settings contains only public fields plus { configured: true } per secret field. Passwords, API keys and OAuth tokens are not returned. Leave secret fields empty on PUT to keep the existing value.
See the OpenAPI specification (tag integrations) for exact schemas.
Related
- API reference - Every endpoint, to try out in the browser
- OpenAPI - API specification (JSON)
- MCP - Connect Cursor, Claude, ChatGPT or Gemini via OAuth
- External notifications - Register emails your own system sent
- Webhooks - Receive events via HTTP POST
- Incoming webhook of an automation - Start an automation with a POST, without an API key
- SSE - Stream events via Server-Sent Events
- Examples - Code and payload examples