# 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 onder **Instellingen → API-sleutels**. Je kunt ze ook via de API aanmaken (vereist een ingelogde sessie, geen API-sleutel):

```
POST /api/api-keys
```

**Headers:**

* `Cookie` - Sessie-auth (vereist voor het aanmaken van sleutels)
* `Content-Type: application/json`

**Body:**

```json
{
  "name": "Mijn integratie",
  "description": "Optionele beschrijving"
}
```

**Response:** De ruwe sleutel wordt **eenmalig** teruggegeven. 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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

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

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

### 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
  * Roteer sleutels periodiek via de app of `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://app.tillor.eu` (of je deployment-URL)

**Organisatie-paden:** Voeg het organisatie-ID toe in het pad:

```
/api/orgs/:orgId/...
```

**Voorbeeld:**

```
GET https://app.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://app.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"
```

***

## 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