Authenticatie

Scopes

Een sleutel draagt een vaste verzameling scopes, gekozen bij het aanmaken. Een verzoek zonder de scope die het endpoint verlangt wordt geweigerd, en de weigering noemt de ontbrekende toestemming.

Eén sleutel voor meerdere organisaties

Een sleutel hoort bij één organisatie en kan alleen voor een andere organisatie handelen waar hij een vrijgave heeft. Een organisatie die klanten beheert, kan haar sleutels toegang geven tot elke klant, met per klant gekozen rechten. Elk verzoek noemt in zijn pad één organisatie en werkt alleen op die organisatie.

Een sleutel toegang geven tot een klant

Roep POST /organizations/{organization}/grants aan met de identificatie van de klant in het pad, en de key_id van de sleutel en de toe te kennen scopes in de body. De aanroepende sleutel heeft keys:admin nodig in zijn eigen organisatie. Aan een klant kunnen alleen scopes worden toegekend die de sleutel al in zijn eigen organisatie heeft, en filings:write vereist bovendien dat de schriftelijke machtiging van de klant eerst wordt bevestigd.

curl "https://passportcraft.com/api/v1/organizations/{client}/grants" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key_id": "K3n9Qw2P", "scopes": ["passports:read", "passports:write"]}'

Wanneer de toegang eindigt

DELETE /organizations/{organization}/grants/{keyId} beëindigt één vrijgave, en de sleutel blijft werken voor elke andere organisatie waarvoor hij een vrijgave heeft. Een klant kan de toegang van een sleutel ook intrekken, in zijn eigen instellingen. Als de samenwerking tussen een klant en uw organisatie eindigt, eindigen daarmee in één keer alle vrijgaves voor die klant. Daarna beantwoordt elk verzoek voor de klant met 404 organization_not_found_or_not_granted, hetzelfde antwoord als voor een organisatie die niet bestaat. Roep GET /organizations aan om de twee te onderscheiden: een organisatie waartoe u de toegang bent kwijtgeraakt, staat er niet meer bij.

Elke vermelding in GET /organizations bevat display_name, de naam van de organisatie, en link_status, met als waarde "accepted" voor een klant die uw organisatie beheert en null voor uw eigen organisatie.

Live sleutels voor een organisatie die klanten beheert

Een organisatie die klanten beheert, kan een live sleutel aanmaken zodra haar eigen abonnement, of dat van minstens één van haar klanten, een betaald Pro- of Scale-abonnement is. Een abonnement in de proefperiode, of met een openstaande betaling, telt niet mee. Elk verzoek wordt nog steeds getoetst aan het abonnement van de organisatie die in het pad wordt genoemd.

Voorbeeld: één planner, tien klanten

Een nachtelijke taak roept GET /organizations aan om de organisaties op te sommen waarvoor zijn sleutel mag handelen, en synchroniseert daarna elke klant apart. Een klant die vertrekt, valt uit de lijst, zodat de taak stopt met die klant aan te roepen in plaats van elke nacht een 404 te loggen.

const base = 'https://passportcraft.com/api/v1'
const headers = { 'Authorization': 'Bearer ' + process.env.PASSPORTCRAFT_API_KEY }

const { data } = await (await fetch(base + '/organizations', { headers })).json()
const clients = data.filter((connection) => connection.link_status === 'accepted')

for (const client of clients) {
  // One organization per request, always named in the path.
  await syncCatalogue(client.organization_id, client.display_name)
}