Autenticación

Ámbitos

Una clave lleva un conjunto fijo de ámbitos, elegido al crearla. Una solicitud sin el ámbito que exige su endpoint se rechaza, y el rechazo nombra el permiso que faltaba.

Una sola clave para varias organizaciones

Una clave pertenece a una organización, y solo puede actuar sobre otra organización donde tenga una concesión. Una organización que gestiona clientes puede conceder a sus claves acceso a cada cliente, con los permisos elegidos por cliente. Cada solicitud nombra una organización en su ruta y actúa solo sobre esa organización.

Dar a una clave acceso a un cliente

Llame a POST /organizations/{organization}/grants con el identificador del cliente en la ruta, y el key_id de la clave y los ámbitos que se conceden en el cuerpo. La clave que hace la llamada necesita keys:admin en su propia organización. A un cliente solo se le pueden conceder ámbitos que la clave ya tenga en su propia organización, y filings:write exige además que se confirme antes la autorización escrita del cliente.

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

Cuando el acceso termina

DELETE /organizations/{organization}/grants/{keyId} termina una concesión, y la clave sigue funcionando en cualquier otra organización sobre la que tenga una concesión. Un cliente también puede quitar el acceso de una clave desde su propia configuración. Poner fin a la colaboración entre un cliente y su organización termina de golpe todas las concesiones sobre ese cliente. A partir de entonces, cada solicitud para ese cliente responde 404 organization_not_found_or_not_granted, la misma respuesta que para una organización que no existe. Para distinguir los dos casos, llame a GET /organizations: una organización sobre la que ha perdido el acceso deja de aparecer en la lista.

Cada entrada de GET /organizations tiene display_name, el nombre de la organización, y link_status, que vale "accepted" para un cliente que gestiona su organización y null para su propia organización.

Claves live para una organización que gestiona clientes

Una organización que gestiona clientes puede crear una clave live cuando su propio plan, o el plan de al menos uno de sus clientes, es un plan Pro o Scale de pago. Un plan en prueba, o con un pago pendiente, no cuenta. Cada solicitud se sigue comprobando contra el plan de la organización nombrada en su ruta.

Ejemplo: un planificador de tareas, diez clientes

Un trabajo nocturno llama a GET /organizations para listar las organizaciones sobre las que su clave puede actuar, y luego sincroniza cada cliente por separado. Un cliente que se marcha desaparece de la lista, así que el trabajo deja de llamarlo en vez de registrar un 404 cada noche.

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