HTTP API
API-Schlüssel, Base URL und Authentifizierung für die Tillor REST API
Zuletzt aktualisiert am
Die Tillor API ist eine REST API. Authentifizieren Sie sich mit einem API-Schlüssel und senden Sie bei jeder Anfrage die richtigen Header. API-Schlüssel gelten pro Konto - ein Schlüssel funktioniert für alle Organisationen, auf die Sie Zugriff haben.
API-Referenz und OpenAPI
- API-Referenz - Jeder Endpunkt mit Parametern und Beispielen; probieren Sie Anfragen direkt im Browser aus
- OpenAPI-Spezifikation - Vollständige API-Dokumentation im JSON-Format für Codegenerierung oder den Import in Postman/Insomnia
API-Schlüssel
Anlegen
API-Schlüssel legen Sie in der Tillor-App über das Benutzermenü unter Konto > API-Schlüssel an (Markierung 1 = Menü, Markierung 2 = API-Schlüssel im Screenshot). Sie können sie auch über die API mit einer angemeldeten Sitzung (ohne API-Schlüssel) anlegen. Siehe die OpenAPI-Spezifikation unter dem Tag api-keys für Pfade sowie Request- und Response-Schemas.
Der Rohschlüssel wird einmalig beim Anlegen oder Neugenerieren zurückgegeben. Bewahren Sie ihn sicher auf; Sie können ihn danach nicht mehr abrufen.
Berechtigungen beschränken
Standardmäßig kann ein Schlüssel alles, was Sie selbst dürfen, in jeder Organisation, in der Sie Mitglied sind. Schalten Sie im Schlüsselfenster Auf ausgewählte Berechtigungen beschränken ein und wählen Sie die Berechtigungen, die die Anbindung braucht, zum Beispiel nur Rechnungen lesen. Ein beschränkter Schlüssel erhält in jeder Organisation die Schnittmenge seiner Berechtigungen und Ihrer dortigen Mitgliedschaft: Ein Schlüssel kann nie mehr als Sie. Ein Aufruf außerhalb der gewählten Berechtigungen erhält 403 Forbidden, genau wie ein Benutzer ohne dieses Recht. Eine Änderung der Berechtigungen gilt innerhalb einer Minute. Über die API: scopes (Liste von Berechtigungs-IDs wie invoices:read, oder null für alles) beim Anlegen und Aktualisieren eines Schlüssels.
Verwendung
Senden Sie den API-Schlüssel im Header x-api-key:
x-api-key: tkn_xxxSchlüssel verwenden das Präfix tkn_. Bei Organisations-Endpunkten steht die Organisations-ID im Pfad (/orgs/org_abc123/...); ein separater Header ist nicht nötig.
Rate Limits
- Standard: 5000 Anfragen pro 60 Sekunden pro Schlüssel
- Bei Überschreitung:
429 Too Many RequestsmitRetry-After - Jede Antwort auf einen API-Schlüssel enthält IETF-
RateLimit-*-Header:
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60RateLimit-Reset ist die Anzahl der Sekunden, bis das aktuelle Zeitfenster neu beginnt. Browser-Clients können diese Header über CORS lesen (Access-Control-Expose-Headers).
Sicherheit
Achtung
- Nie API-Schlüssel in clientseitigem Code oder öffentlichen Repositories offenlegen
- Generieren Sie Schlüssel regelmäßig über Neu generieren in der App neu (OpenAPI:
POST /api/api-keys/:id/renew) - Löschen Sie ungenutzte Schlüssel mit
DELETE /api/api-keys/:id
Base URL und Organisationskontext
Base URL: https://tillor.eu (oder Ihre Deployment-URL; OpenAPI nennt {APP_URL}/api)
Organisationspfade: Fügen Sie die Organisations-ID in den Pfad ein:
/api/orgs/:orgId/...Beispiel:
GET https://tillor.eu/api/orgs/org_abc123/customersErforderlicher Header für Organisations-Endpunkte: x-api-key: tkn_xxx. Die Organisations-ID steht im Pfad.
Beispiel: cURL
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
-H "x-api-key: tkn_xxx" \
-H "Content-Type: application/json"Integrationen (Marketplace)
Organisations-Integrationen (früher „Apps“ in der API) verwenden pro Typ eine Ressource unter /api/orgs/:orgId/integrations/{integrationType}. Erforderliche Berechtigungen sind organization:integrations:read und organization:integrations:write (ersetzt organization:apps:*).
| Methode | Pfad | Beschreibung |
|---|---|---|
| GET | /integrations/{integrationType} | Status (installed, available) und geschwärzte settings |
| POST | /integrations/{integrationType} | Installieren (optional settings im Body; OAuth kann redirectUrl zurückgeben) |
| PUT | /integrations/{integrationType} | Einstellungen aktualisieren (settings im Body) |
| DELETE | /integrations/{integrationType} | Deinstallieren |
Bei GET und nach PUT enthält settings nur öffentliche Felder plus pro geheimem Feld { configured: true }. Passwörter, API-Keys und OAuth-Tokens kommen nicht zurück. Lassen Sie geheime Felder bei PUT leer, um den bestehenden Wert zu behalten.
Genaue Schemas finden Sie in der OpenAPI-Spezifikation (Tag integrations).
Verwandt
- API-Referenz - Jeder Endpunkt, im Browser ausprobierbar
- OpenAPI - API-Spezifikation (JSON)
- MCP - Cursor, Claude, ChatGPT oder Gemini über OAuth anbinden
- Externe Benachrichtigungen - E-Mails registrieren, die Ihr eigenes System versendet hat
- Webhooks - Events per HTTP POST empfangen
- Eingehender Webhook einer Automatisierung - Eine Automatisierung mit einem POST starten, ohne API-Schlüssel
- SSE - Events per Server-Sent Events streamen
- Beispiele - Code- und Payload-Beispiele