Authenticatie en rechten

Elke aanroep draagt een API-token. Het token bepaalt over welke werkruimte de aanroep gaat en welke endpoints hij mag gebruiken.

Stuur het token mee

Stuur het token bij elke aanroep mee als bearer-token in de header Authorization:

curl "https://picked.nl/api/v1/stock?sku=YOUR-SKU" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json"

Een aanroep zonder geldig token geeft 401 met de code unauthenticated. Dat geldt ook voor een ingetrokken token.

Eén token, één werkruimte

Een token hoort bij de werkruimte waarin het is uitgegeven, en elke aanroep ermee leest en schrijft alleen de gegevens van die werkruimte. Je stuurt nooit een werkruimte-id mee: Picked haalt die uit het token. De basis-URL is https://picked.nl/api/v1, voor elke werkruimte. Roep je de API in plaats daarvan aan op het eigen adres van je werkruimte, dan moet het token bij die werkruimte horen. Anders geeft de aanroep 403 met de code forbidden. De nodecatalogus is voor elke werkruimte gelijk en slaat deze controle over.

Rechten

Bij het uitgeven van een token kies je de rechten. Elk endpoint heeft er één nodig:

Endpoint	Recht
`POST /api/v1/orders`	`orders:write`
`GET /api/v1/orders/{id}`	`orders:read`
`GET /api/v1/orders/changes`	`orders:read`
`GET /api/v1/stock`	`stock:read`
`GET /api/v1/stock/changes`	`stock:read`
`GET /api/v1/stock/changes/feed`	`stock:read`
`POST /api/v1/receipts`	`receipts:write`
`GET /api/v1/receipts/{id}`	`receipts:write`
`POST /api/v1/process-events/{eventKey}`	`process-events:write`
`POST /api/v1/processes/{process}/runs`	`process-runs:write`
`GET /api/v1/process-runs/{id}`	`process-runs:write`
`POST /api/v1/process-runs/callbacks/{token}`	geen token
`GET /api/v1/node-catalog`	elk geldig token
`GET /api/v1/warehouses`	elk API-token
`GET /api/v1/locations`	elk API-token

Waarom het terugbellen er geen nodig heeft: Laat je systeem over een stap beslissen.

Een token zonder het recht dat een endpoint nodig heeft, geeft 403 met de code missing_ability. Je kunt geen recht toevoegen aan een bestaand token: geef een nieuw token uit met de rechten die je nodig hebt, en trek het oude in.

Eén token per koppeling

Geef elke koppeling een eigen token, met alleen de rechten die ze gebruikt. Een webshop die alleen voorraad toont, krijgt een token met stock:read; het ERP dat orders stuurt, krijgt een token met orders:write. Zo kan een uitgelekt token zo weinig mogelijk, en trek je de toegang van één koppeling in zonder de andere stil te leggen.

De recente aanroepen van elk token staan onder Verzoeken, naast het token op de pagina API-tokens: de laatste 100 aanroepen, 30 dagen bewaard, met hun status. Request-bodies worden nooit opgeslagen.

Hoe lang een token werkt

Een token heeft geen vervaldatum. Het blijft werken tot je het intrekt, of tot het teamlid dat het uitgaf uit je werkruimte wordt verwijderd: wie je verwijdert, neemt al zijn tokens mee. De pagina API-tokens laat zien wie elk token uitgaf en wanneer het voor het laatst is gebruikt.

Geef het token van een koppeling dus uit vanaf een account dat blijft, niet vanaf het account van iemand die kan vertrekken.

Trek een token in

Kies Intrekken naast het token op de pagina API-tokens. Het werkt meteen niet meer: de volgende aanroep ermee geeft 401. Trek een token in zodra je vermoedt dat het is uitgelekt, en wanneer de koppeling die het gebruikte verdwijnt. Voor intrekken heb je dezelfde permissie nodig als voor uitgeven.

Vervang een token

Zo vervang je een token zonder dat je koppeling stilvalt:

Geef een nieuw token uit met dezelfde rechten.
Zet het nieuwe token in de configuratie van je koppeling en zet die live.
Controleer op de pagina API-tokens dat het oude token niet meer wordt gebruikt.
Trek het oude token in.