# HTTP API (/ontwikkelaars/http)



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

* **[API Playground](https://tillor.eu/api/playground)** - Probeer endpoints direct in de browser met je API-sleutel
* **[OpenAPI-specificatie](https://tillor.eu/api/openapi.json)** - Volledige API-documentatie in JSON-formaat voor codegeneratie of import in Postman/Insomnia

***

## API-sleutels [#api-sleutels]

### Aanmaken [#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](https://tillor.eu/api/openapi.json) onder tag `api-keys` voor paden, request- en response-schema's.

<DocScreenshot src="/screenshots/http/api-keys-nav.png" alt="API-sleutels in accountinstellingen" />

De ruwe sleutel wordt **eenmalig** teruggegeven bij aanmaken of regenereren. Bewaar deze veilig; je kunt hem daarna niet meer ophalen.

### Gebruik [#gebruik]

Stuur de API-sleutel in de `x-api-key` header:

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

Sleutels gebruiken het `tkn_`-voorvoegsel. Alle organisatie-endpoints vereisen ook het organisatie-ID:

```http
X-Tillor-Org-Id: org_abc123
```

### Rate limits [#rate-limits]

* **Standaard:** 200 requests per 60 seconden per sleutel
* Bij overschrijding: `429 Too Many Requests`

### Beveiliging [#beveiliging]

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

***

## Base URL en organisatie-context [#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/customers
```

**Vereiste headers voor organisatie-endpoints:**

* `x-api-key: tkn_xxx` - API-sleutel
* `X-Tillor-Org-Id: org_abc123` - Organisatie-ID (moet overeenkomen met het pad)

***

## Voorbeeld: cURL [#voorbeeld-curl]

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

***

## Integraties (marketplace) [#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](https://tillor.eu/api/openapi.json) (tag `integrations`) voor exacte schema's.

***

## Gerelateerd [#gerelateerd]

* [API Playground](https://tillor.eu/api/playground) - Endpoints uitproberen in de browser
* [OpenAPI](https://tillor.eu/api/openapi.json) - API-specificatie (JSON)
* [Webhooks](/ontwikkelaars/webhooks) - Ontvang events via HTTP POST
* [SSE](/ontwikkelaars/sse) - Stream events via Server-Sent Events
* [Voorbeelden](/ontwikkelaars/voorbeelden) - Code- en payload-voorbeelden