Authenticatie

Authenticeer met een Bearer-token:

curl "https://app.bidvise.com/api/v2/items" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

Elk verzoek heeft er een nodig. Er is geen ongeauthenticeerd deel van de API.

Sleutels

Een API-sleutel wordt aangemaakt in de Bidvise-backoffice en hoort bij precies één veilinghuis. Behandel de sleutel als een ondoorzichtige string: bewaar hem als geheim, stuur hem ongewijzigd mee, en ontleed hem niet.

Rechten

Een sleutel draagt een rol, en die rol bepaalt welke resources de sleutel mag raken. Rechten zijn fijnmazig: ze worden per resource én per actie gegeven, als resource.actie: auctions.read, lots.read, enzovoort. Dezelfde woordenlijst regelt ook de medewerkersaccounts in de backoffice, dus een sleutel kan nooit iets krijgen wat een mens niet kan krijgen.

Geef een sleutel de smalste rol die zijn werk doet. Een rapportagekoppeling die alleen de catalogus nodig heeft, krijgt auctions.read en lots.read; verder komt hij nergens, en hij krijgt er ook niets stilletjes bij zodra er nieuwe endpoints komen.

Wordt er geen rol gekozen, dan erft de sleutel de toegang van het account dat hem heeft aangemaakt. Handig voor een eerste koppeling, en verkeerd voor alles wat blijft staan: een sleutel die door een eigenaarsaccount is gemaakt, kan alles wat die eigenaar kan.

Elk endpoint in deze referentie vermeldt welk recht het vereist. Zonder dat recht volgt een 403:

{
  "type": "https://docs.bidvise.com/api/problems/forbidden",
  "title": "Insufficient permissions",
  "status": 403,
  "detail": "This API key does not have the lots.read permission."
}

Items schrijven vereist lots.write en lots.read, omdat het antwoord het item bevat. Een bestaande inbrenger of categorie koppelen vereist daarnaast respectievelijk seller_profiles.read of categories.read; schrijfrechten voor die verwijzingen zijn niet nodig.

Wat een sleutel ziet

De sleutel is de afbakening. Elke response wordt gefilterd op het huis waar de sleutel bij hoort, en geen enkele parameter verbreedt dat.

Een kavel van een ander huis wordt gemeld als 404 Not Found, niet als 403 Forbidden: dat verschil telt, want een 403 zou bevestigen dat het object bestaat. Of een ander huis een kavel op een bepaald ID heeft, is niets wat een API-sleutel hoort te kunnen achterhalen.

Een sleutel veilig houden

Sleutels zijn geheimen. Houd ze op de server, in de omgeving of een secret store: niet in een browser, een mobiele app of versiebeheer. Wie de sleutel heeft, kan de hele catalogus lezen waar hij bij hoort.

Is een sleutel uitgelekt, trek hem dan in via de backoffice; dat werkt direct. Roteren zonder downtime gaat zo: maak de nieuwe sleutel aan, rol hem uit, en trek daarna pas de oude in. Tijdens de overlap werken ze allebei.

Fouten

Een ontbrekende of onbekende sleutel levert een RFC 9457-problem-document op:

{
  "type": "https://docs.bidvise.com/api/problems/unauthorized",
  "title": "Missing credentials",
  "status": 401,
  "detail": "Provide your API key as: Authorization: Bearer <key>"
}

Een sleutel die geldig is maar niet aan een huis gekoppeld, levert 403 op. Zie conventies voor de foutvorm in het algemeen.