# HTTP API (/de-DE/ontwikkelaars/http)

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-referentie-en-openapi]

- **[API-Referenz](/api-referentie)** - Jeder Endpunkt mit Parametern und Beispielen; probieren Sie Anfragen direkt im Browser aus
- **[OpenAPI-Spezifikation](https://tillor.eu/api/openapi.json)** - Vollständige API-Dokumentation im JSON-Format für Codegenerierung oder den Import in Postman/Insomnia

---

## API-Schlüssel [#api-sleutels]

### Anlegen [#aanmaken]

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](https://tillor.eu/api/openapi.json) unter dem Tag `api-keys` für Pfade sowie Request- und Response-Schemas.

<DocScreenshot src="/screenshots/http/api-keys-nav.png" alt="API-Schlüssel in den Kontoeinstellungen" />

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 [#rechten-beperken]

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 [#gebruik]

Senden Sie den API-Schlüssel im Header `x-api-key`:

```http
x-api-key: tkn_xxx
```

Schlü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 [#rate-limits]

- **Standard:** 5000 Anfragen pro 60 Sekunden pro Schlüssel
- Bei Überschreitung: `429 Too Many Requests` mit `Retry-After`
- Jede Antwort auf einen API-Schlüssel enthält IETF-`RateLimit-*`-Header:

```http
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60
```

`RateLimit-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 [#beveiliging]

<Callout type="warn" title="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`
</Callout>

---

## Base URL und Organisationskontext [#base-url-en-organisatie-context]

**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/customers
```

**Erforderlicher Header für Organisations-Endpunkte:** `x-api-key: tkn_xxx`. Die Organisations-ID steht im Pfad.

---

## Beispiel: cURL [#voorbeeld-curl]

```bash
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
  -H "x-api-key: tkn_xxx" \
  -H "Content-Type: application/json"
```

---

## Integrationen (Marketplace) [#integraties-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](https://tillor.eu/api/openapi.json) (Tag `integrations`).

---

## Verwandt [#gerelateerd]

- [API-Referenz](/api-referentie) - Jeder Endpunkt, im Browser ausprobierbar
- [OpenAPI](https://tillor.eu/api/openapi.json) - API-Spezifikation (JSON)
- [MCP](/ontwikkelaars/mcp) - Cursor, Claude, ChatGPT oder Gemini über OAuth anbinden
- [Externe Benachrichtigungen](/ontwikkelaars/externe-notificaties) - E-Mails registrieren, die Ihr eigenes System versendet hat
- [Webhooks](/ontwikkelaars/webhooks) - Events per HTTP POST empfangen
- [Eingehender Webhook einer Automatisierung](/ontwikkelaars/automatiseringen#een-automatisering-starten-met-een-webhook) - Eine Automatisierung mit einem POST starten, ohne API-Schlüssel
- [SSE](/ontwikkelaars/sse) - Events per Server-Sent Events streamen
- [Beispiele](/ontwikkelaars/voorbeelden) - Code- und Payload-Beispiele