Authentication

Scopes

A key carries a fixed set of scopes, chosen when it is created. A request that lacks the scope its endpoint requires is refused, and the refusal names the permission that was missing.

One key for several organizations

A key belongs to one organization, and it can act on another organization only where it holds a grant. An organization that manages clients can grant its keys access to each client, with permissions chosen per client. Each request names one organization in its path and acts on that organization alone.

Giving a key access to a client

Call POST /organizations/{organization}/grants with the client's id in the path, and the key's key_id and the scopes to grant in the body. The key that makes the call needs keys:admin on its own organization. A client can be granted only scopes the key already holds on its own organization, and filings:write also needs the client's written authorisation to be confirmed first.

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

When access ends

DELETE /organizations/{organization}/grants/{keyId} ends one grant, and the key keeps working on every other organization it holds a grant on. A client can also remove a key's access in its own Settings. Ending the arrangement between a client and your organization ends every grant on that client at once. After that, each request for the client answers 404 organization_not_found_or_not_granted, the same answer as for an organization that does not exist. To tell the two apart, call GET /organizations: an organization you lost access to is no longer listed.

Each entry in GET /organizations has display_name, the organization's name, and link_status, which is "accepted" for a client your organization manages and null for your own organization.

Live keys for an organization that manages clients

An organization that manages clients can create a live key when its own plan, or the plan of at least one of its clients, is a paid Pro or Scale plan. A plan on a trial, or with a failed payment, does not count. Each request is still checked against the plan of the organization named in its path.

Example: one scheduler, ten clients

A nightly job calls GET /organizations to list the organizations its key can act on, then syncs each client separately. A client that leaves drops out of the list, so the job stops calling it instead of logging a 404 every night.

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