# Authenticatie

> API-sleutels, lees- en schrijfrechten, het intrekken van sleutels en het veilig houden ervan.

De API gebruikt geheime API-sleutels. Elke sleutel behoort tot één werkruimte.

## Stuur de sleutel

Plaats de sleutel in de `Authorization` header als een bearer token:

```http
GET /api/v1/workspace HTTP/1.1
Host: tradecatalog.app
Authorization: Bearer tc_live_Xk2…
```

```bash
curl https://tradecatalog.app/api/v1/workspace \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
```

Sleutels beginnen altijd met `tc_live_`. Er zijn geen test-sleutels: probeer dingen uit op een werkruimte met voorbeeldgegevens, of lees voordat je schrijft.

## Maak een sleutel

Alleen de werkruimte **eigenaar** of een **beheerder** kan sleutels maken, in **Instellingen → API**.

| Instelling        | Wat het betekent                                                                       |
| ----------------- | -------------------------------------------------------------------------------------- |
| Naam              | Uw label, bijv. “Sage stock sync”. Zichtbaar in Instellingen en in de activiteitenlog. |
| Alleen lezen      | Alleen `GET` aanvragen.                                                                |
| Lezen & schrijven | Ook `PUT /products`, `PUT /customers` en `PATCH /orders/{id}`.                         |

De sleutel wordt **één keer** getoond. We bewaren alleen een SHA-256-hash, dus niemand bij TradeCatalog kan het opnieuw zien. Instellingen toont de eerste paar tekens (zoals `tc_live_Xk2m…`) zodat u sleutels kunt onderscheiden.

Een werkruimte kan maximaal **20 actieve sleutels** hebben. Geef elke systeem zijn eigen sleutel, zodat u er één kunt intrekken zonder de anderen te verstoren.

## Wie mag sleutels hebben

De werkruimte heeft een van deze nodig om sleutels te maken:

- een actieve abonnement
- een Pro proefperiode
- een pilot account (afgesproken met Happy Webs)

Demo werkruimtes kunnen geen sleutels maken of gebruiken.

Als het abonnement verloopt, krijg je 14 dagen graat. Daarna keert de werkruimte terug naar Free. Bestaande sleutels kunnen nog steeds lezen, maar API-schrijven mislukken met `403 read_only` tot Pro weer actief is. Cataloguswijzigingen en koperbestellingen in de app blijven werken.

## Wat een sleutel kan doen

Een sleutel werkt met de **rechten van de persoon die hem heeft gemaakt**, zoals ze nu zijn. Een sleutel gemaakt door een eigenaar of beheerder kan elke klant, elke klantprijs, elke bestelling en het activiteitenlogboek lezen. Behandel het als het wachtwoord van die persoon. Een sleutel gemaakt door iemand die beperkt is tot hun toegewezen klanten of regio’s ziet alleen die klanten en hun bestellingen, prijzen en activiteiten; elke andere klant of bestelling retourneert `404`, hetzelfde als een die niet bestaat, en prijsveranderingen retourneert `403`.

Als die persoon later een nauwer rol krijgt, verandert de sleutel met hen: een schrijf die de nieuwe rol niet toestaat mislukt met `403 forbidden`, hetzelfde als in de app. Als ze de werkruimte verlaten, stopt de sleutel met `401 key_owner_removed`. Maak een nieuwe sleutel van iemand die nog toegang heeft.

## Laatst gebruikt en intrekken

Instellingen toont wanneer elke sleutel het laatst is gebruikt (bijgewerkt maximaal een keer per uur). Kies **In trekken** om een sleutel direct te stoppen. De volgende aanvraag met deze krijgt `401 unauthorized`. Ingetrokken sleutels kunnen niet hersteld worden.

## Wie de wijzigingen worden gelogd als

Schrijven verschijnen in het activiteitenlogboek van de werkruimte als `API key “Sage stock sync”`. Bestellingsstatuswijzigingen worden geregistreerd tegen de persoon die de sleutel heeft gemaakt.

## Houd sleutels veilig

- Houd sleutels op je server, in omgevingsvariabelen of een geheimenbeheerder.
- Plaats nooit een sleutel in een webpagina, browserextensie of mobiele app. De API stelt geen browser (CORS) aanvragen toe om deze reden.
- Commit geen sleutel naar git. Als je dat doet, trek hem in en maak er een nieuwe van.
- Gebruik een alleen-lezen sleutel waar je alleen hoeft te lezen.

## Fouten

| Status | Code                 | Waarom                                                                                                                                                           |
| ------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401    | `unauthorized`       | Geen `Authorization` header, een verkeerd gevormde, een onbekende of ingetrokken sleutel, of een demo werkruimte. Het antwoord heeft `WWW-Authenticate: Bearer`. |
| 401    | `key_owner_removed`  | De persoon die de sleutel heeft gemaakt heeft geen toegang meer tot de werkruimte. Maak een nieuwe sleutel.                                                      |
| 403    | `insufficient_scope` | Een alleen-lezen sleutel probeert te schrijven.                                                                                                                  |
| 403    | `forbidden`          | De persoon die de sleutel heeft gemaakt is niet toegestaan om dat te doen (bijvoorbeeld, een Viewer kan niet schrijven).                                         |
| 403    | `read_only`          | API-schrijven zijn niet beschikbaar op het Free-plan.                                                                                                            |

Zie [Fouten](/docs/api/errors) voor de volledige lijst.

**AI-apps gebruiken een ander inlogproces:** Claude, ChatGPT en andere MCP-clients gebruiken geen API-sleutels. Elke persoon meldt zich aan met hun eigen inloggegevens via OAuth. Zie [MCP](/docs/mcp).