# API-keys beheren

Een API-key geeft één koppeling toegang tot gegevens van je organisatie. Maak bij voorkeur een aparte key per koppeling en omgeving, zodat je gebruik kunt herkennen en toegang gericht kunt intrekken.

> **Nieuwe conceptaccounts:** alleen **API-gebruik lezen** is beschikbaar. Pakketgegevens en betaald gebruik zijn niet geactiveerd. Een key verleent nooit meer producttoegang dan de organisatie zelf heeft.

## Een key aanmaken

1. [Log in op de console](/account/) met je e-mailadres, wachtwoord en 2FA.
2. Open **API-keys** in de navigatie.
3. Vul onder **Nieuwe API-key** een herkenbare naam van 1–100 tekens in, bijvoorbeeld `Orderkoppeling`.
4. Kies **Systeemkoppeling** voor normaal API-gebruik.
5. Selecteer de rechten die de koppeling nodig heeft. Voor de eerste test kies je **API-gebruik lezen**.
6. Klik op **API-key aanmaken**.

Je moet de rol `owner` of `admin` hebben om het formulier te gebruiken. Zie je het formulier niet, vraag dan je organisatiebeheerder om een key met de benodigde rechten.

Bewaar de volledige key direct. Hij begint met `vlw_` en wordt uitsluitend na het aanmaken getoond. Bij later terugkijken zie je de naam, het type, de rechten, de status en de vervaldatum.

> Voor aanmaken en intrekken moet je email bevestigd zijn, 2FA afgerond zijn en je laatste volledige login maximaal 15 minuten geleden zijn. Bij een melding over opnieuw inloggen: log uit en log weer in, inclusief 2FA.

## Velden van een nieuwe key

| Veld in de console | Verplicht? | Hoe invullen? | Voorbeeld |
| --- | --- | --- | --- |
| **Naam** | Ja | Herkenbare naam van de koppeling of omgeving, 1–100 tekens en maximaal 100 UTF-8-bytes. | `Orderkoppeling productie` |
| **Type** | Ja, al vooringevuld | Kies **Systeemkoppeling** voor normale API-aanvragen. **MCP / AI** is alleen voor leesrechten. | Systeemkoppeling |
| **Rechten** | Minstens één | Vink precies de benodigde rechten aan. Er zijn vier mogelijke rechten. | API-gebruik lezen |

De console vult de organisatie en geldigheidsduur automatisch in: je huidige organisatie en 90 dagen. Je typt niet zelf een sleutel, key-ID, vervaldatum of organisatie-ID in.

Voor een eerste leesproef vink je **API-gebruik lezen** aan. Het formulier heeft **Eigen leveringen lezen** standaard aangevinkt; zet dat uit als je het niet nodig hebt. Voor een koppeling die leveringen aanmaakt en terugleest kies je **Leveringen aanleveren en bijwerken** én **Eigen leveringen lezen**.

Na aanmaken verschijnt de volledige `vlw_`-key eenmaal. Kopieer de gehele waarde zonder extra spaties naar je geheime configuratie. De naam is een herkenningslabel en is niet de sleutel die je in de Authorization-header gebruikt.

## Kies het juiste type

| Type in de console | API-waarde | Gebruik |
| --- | --- | --- |
| Systeemkoppeling | `standard` | Een normale koppeling met gekozen lees- en/of schrijfrechten. |
| MCP / AI (alleen lezen) | `mcp` | Alleen leesrechten. Voorbereiding op MCP; een werkende MCP-server is nog niet beschikbaar. |

Een MCP-key met `deliveries:write` wordt geweigerd. Ook een gewone systeemkey heeft alleen de expliciet geselecteerde scopes.

## Welke rechten geef ik?

| Consolelabel | Scope | Geeft toegang tot |
| --- | --- | --- |
| Eigen leveringen lezen | `deliveries:read` | Leveringen, gebeurtenissen, pogingen, referentiewaarden en geregistreerde vervoerders van je organisatie. |
| Leveringen aanleveren en bijwerken | `deliveries:write` | Leveringen schrijven, gebeurtenissen/pogingen toevoegen en adressen controleren. |
| Oracle raadplegen | `oracle:read` | De beschikbare geaggregeerde oracle-inzichten. |
| API-gebruik lezen | `usage:read` | Dagtotalen en recente aanvragen van je organisatie. |

Schrijfrecht geeft niet automatisch leesrecht. Heeft je integratie beide nodig, selecteer beide. Aanmaken en intrekken van keys doe je in de console. Gebruik de gemaakte key vervolgens voor [aanvragen aan de API](/authenticatie/).

## Geldigheid en status

De console maakt keys met een geldigheid van **90 dagen**. De vervaldatum staat bij de key in het overzicht.

- **Actief:** de key is niet ingetrokken en nog niet verlopen.
- **Verlopen:** de vervaldatum is bereikt; nieuwe aanvragen worden geweigerd.
- **Ingetrokken:** je hebt de toegang beëindigd. De key kan niet weer worden aangezet.

Tijden in de console zijn UTC. Er is geen automatische vernieuwing of wijziging van een bestaande key. Maak een vervanger als rechten of geldigheid moeten veranderen.

## Een key vervangen

Maak een nieuwe key met de juiste rechten. Zet die in de geheime configuratie van je integratie en doe een testaanvraag. Controleer het gebruik onder de nieuwe naam. Trek daarna de oude key in. Bij een uitgelekte key trek je de oude sleutel zo snel mogelijk in.

## Een key intrekken

Hiervoor zijn geen losse invoervelden. Controleer eerst de **naam**, **rechten** en **status** in de juiste rij, zodat je de bedoelde koppeling kiest.

Zoek de key in **API-keys** en klik op **Intrekken**. Nieuwe aanvragen met die key krijgen direct `401 Unauthorized`. De key en de historische gebruikslogs blijven zichtbaar; de logs worden niet verwijderd.

Je kunt deze actie niet ongedaan maken. Maak zo nodig een nieuwe key. Wachtwoordherstel of uitloggen trekt API-keys niet automatisch in.

## Ik ben de volledige key kwijt

Een bestaande key is niet opnieuw uit te lezen. Trek hem in de console in en maak een nieuwe. Namen hoeven niet uniek te zijn; kies zelf onderscheidende namen om verwarring te voorkomen.