Autenticazione

Ambiti

Una chiave porta un insieme fisso di ambiti, scelto al momento della creazione. Una richiesta priva dell'ambito richiesto dal proprio endpoint viene rifiutata, e il rifiuto nomina il permesso mancante.

Una sola chiave per più organizzazioni

Una chiave appartiene a un'organizzazione e può agire su un'altra organizzazione solo dove dispone di una concessione. Un'organizzazione che gestisce clienti può concedere alle proprie chiavi l'accesso a ciascun cliente, con permessi scelti per ogni cliente. Ogni richiesta indica un'organizzazione nel proprio percorso e agisce solo su quell'organizzazione.

Dare a una chiave l'accesso a un cliente

Richiami POST /organizations/{organization}/grants con l'identificativo del cliente nel percorso, e il key_id della chiave e gli ambiti da concedere nel corpo. La chiave usata per la chiamata deve disporre di keys:admin nella propria organizzazione. A un cliente possono essere concessi solo ambiti che la chiave possiede già nella propria organizzazione, e filings:write richiede inoltre che l'autorizzazione scritta del cliente sia prima confermata.

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

Quando l'accesso termina

DELETE /organizations/{organization}/grants/{keyId} pone fine a una concessione, e la chiave continua a funzionare su ogni altra organizzazione su cui dispone di una concessione. Un cliente può anche rimuovere l'accesso di una chiave dalle proprie impostazioni. Porre fine alla collaborazione fra un cliente e la Sua organizzazione pone fine in un colpo solo a tutte le concessioni su quel cliente. Da quel momento, ogni richiesta per il cliente riceve come risposta 404 organization_not_found_or_not_granted, la stessa risposta prevista per un'organizzazione inesistente. Per distinguere i due casi, richiami GET /organizations: un'organizzazione di cui ha perso l'accesso non compare più nell'elenco.

Ogni voce di GET /organizations riporta display_name, il nome dell'organizzazione, e link_status, che vale "accepted" per un cliente gestito dalla Sua organizzazione e null per la Sua stessa organizzazione.

Chiavi live per un'organizzazione che gestisce clienti

Un'organizzazione che gestisce clienti può creare una chiave live quando il proprio piano, o il piano di almeno uno dei propri clienti, è un piano Pro o Scale a pagamento. Un piano in prova, o con un pagamento in arretrato, non conta. Ogni richiesta viene comunque verificata rispetto al piano dell'organizzazione indicata nel percorso.

Esempio: un pianificatore, dieci clienti

Un job notturno richiama GET /organizations per elencare le organizzazioni su cui la propria chiave può agire, poi sincronizza ogni cliente separatamente. Un cliente che se ne va esce dall'elenco, così il job smette di richiamarlo invece di registrare un 404 ogni notte.

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