Authentification

Portées

Une clé porte un ensemble fixe de portées, choisi à sa création. Une requête dépourvue de la portée exigée par son point de terminaison est refusée, et le refus nomme la permission manquante.

Une seule clé pour plusieurs organisations

Une clé appartient à une organisation, et elle ne peut agir pour une autre organisation que là où elle détient une autorisation. Une organisation qui gère des clients peut accorder à ses clés l'accès à chaque client, avec des permissions choisies pour chacun. Chaque requête nomme une organisation dans son chemin et n'agit que sur cette organisation.

Donner à une clé l'accès à un client

Appelez POST /organizations/{organization}/grants avec l'identifiant du client dans le chemin, et le key_id de la clé ainsi que les portées à accorder dans le corps. La clé appelante doit disposer de keys:admin sur sa propre organisation. Un client ne peut recevoir que des portées que la clé détient déjà sur sa propre organisation, et filings:write exige en outre que l'autorisation écrite du client soit d'abord confirmée.

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"]}'

Quand l'accès prend fin

DELETE /organizations/{organization}/grants/{keyId} met fin à une autorisation ; la clé continue de fonctionner sur toute autre organisation où elle détient une autorisation. Un client peut aussi retirer l'accès d'une clé depuis ses propres paramètres. Mettre fin à la collaboration entre un client et votre organisation met fin d'un coup à toutes les autorisations sur ce client. Ensuite, chaque requête pour ce client reçoit la réponse 404 organization_not_found_or_not_granted, la même réponse que pour une organisation qui n'existe pas. Pour distinguer les deux cas, appelez GET /organizations : une organisation à laquelle vous avez perdu l'accès n'apparaît plus dans la liste.

Chaque entrée de GET /organizations comporte display_name, le nom de l'organisation, et link_status, qui vaut "accepted" pour un client géré par votre organisation, et null pour votre propre organisation.

Clés live pour une organisation qui gère des clients

Une organisation qui gère des clients peut créer une clé live quand sa propre offre, ou l'offre d'au moins un de ses clients, est une offre Pro ou Scale payante. Une offre en période d'essai, ou avec un paiement en retard, ne compte pas. Chaque requête reste vérifiée par rapport à l'offre de l'organisation nommée dans son chemin.

Exemple : un planificateur, dix clients

Une tâche nocturne appelle GET /organizations pour lister les organisations sur lesquelles sa clé peut agir, puis synchronise chaque client séparément. Un client qui part disparaît de la liste, si bien que la tâche cesse de l'appeler au lieu de journaliser un 404 chaque nuit.

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)
}