Authentifizierung

Scopes

Ein Schlüssel trägt eine feste Menge an Scopes, die bei seiner Erzeugung gewählt wird. Eine Anfrage ohne den vom Endpunkt verlangten Scope wird abgelehnt, und die Ablehnung benennt die fehlende Berechtigung.

Ein Schlüssel für mehrere Organisationen

Ein Schlüssel gehört zu einer Organisation und kann nur dort für eine andere Organisation handeln, wo er eine Freigabe besitzt. Eine Organisation, die Kunden verwaltet, kann ihren Schlüsseln Zugriff auf jeden Kunden gewähren, mit Berechtigungen, die pro Kunde gewählt werden. Jede Anfrage nennt eine Organisation in ihrem Pfad und wirkt sich nur auf diese Organisation aus.

Einem Schlüssel Zugriff auf einen Kunden geben

Rufen Sie POST /organizations/{organization}/grants auf, mit der Kennung des Kunden im Pfad und der key_id des Schlüssels sowie den zu gewährenden Scopes im Body. Der aufrufende Schlüssel benötigt keys:admin in seiner eigenen Organisation. Einem Kunden können nur Scopes gewährt werden, die der Schlüssel bereits in seiner eigenen Organisation besitzt, und filings:write erfordert außerdem, dass die schriftliche Vollmacht des Kunden zuerst bestätigt wird.

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

Wenn der Zugriff endet

DELETE /organizations/{organization}/grants/{keyId} beendet eine Freigabe; der Schlüssel funktioniert bei jeder anderen Organisation, für die er eine Freigabe besitzt, weiterhin. Ein Kunde kann den Zugriff eines Schlüssels auch in seinen eigenen Einstellungen entfernen. Endet die Zusammenarbeit zwischen einem Kunden und Ihrer Organisation, enden damit alle Freigaben für diesen Kunden gleichzeitig. Danach beantwortet jede Anfrage für den Kunden mit 404 organization_not_found_or_not_granted — derselben Antwort wie für eine Organisation, die es nicht gibt. Um die beiden zu unterscheiden, rufen Sie GET /organizations auf: Eine Organisation, zu der Sie den Zugriff verloren haben, wird dort nicht mehr aufgeführt.

Jeder Eintrag in GET /organizations enthält display_name, den Namen der Organisation, sowie link_status. Der Wert ist "accepted" für einen Kunden, den Ihre Organisation verwaltet, und null für Ihre eigene Organisation.

Live-Schlüssel für eine Organisation, die Kunden verwaltet

Eine Organisation, die Kunden verwaltet, kann einen Live-Schlüssel erstellen, wenn ihr eigener Tarif oder der Tarif mindestens eines ihrer Kunden ein bezahlter Pro- oder Scale-Tarif ist. Ein Tarif in der Testphase oder mit einer offenen Zahlung zählt nicht. Jede Anfrage wird weiterhin gegen den Tarif der im Pfad genannten Organisation geprüft.

Beispiel: ein Scheduler, zehn Kunden

Ein nächtlicher Job ruft GET /organizations auf, um die Organisationen aufzulisten, für die sein Schlüssel handeln darf, und synchronisiert dann jeden Kunden einzeln. Verlässt ein Kunde die Liste, fällt er einfach heraus, sodass der Job aufhört, ihn aufzurufen, statt jede Nacht ein 404 zu protokollieren.

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