Authentication
Authentication
Every request carries a secret key in the Authorization header. There is no other way in, and no request is ever authenticated by a session cookie.
Keys
A key is shown once, at the moment it is created. Keep it somewhere the servers can read it and a browser cannot.
- pc_sk_live_…
- pc_sk_test_…
Test and live stay separate
The mode is bound into the credential itself rather than passed as a parameter, so a test key can neither read nor change live data. A misrouted request fails instead of reaching the wrong catalogue. Test passports are deleted 90 days after the passport itself was last edited.
Sending the key
Bearer authentication over HTTPS. Nothing else is accepted, and a request without the header is refused before it reaches any resource.
curl "https://passportcraft.com/api/v1/whoami" \
-H "Authorization: Bearer pc_sk_live_…"Browser credentials are deliberately unsupported. A key belongs on a server, and a key in front-end code is a key that has been published.
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.
documents:read
documents:write
filings:write
passports:read
- get
/organizations/{organization}/capabilitiesDescribe what this credential may do for this organization. - get
/organizations/{organization}/passportsList passports. - get
/organizations/{organization}/passports/{id}Fetch one passport. - post
/organizations/{organization}/passports/{id}/validateCheck a passport against its category schema without saving. - get
/organizations/{organization}/passports/{id}/linksFetch the public and GS1 Digital Link URLs. - get
/organizations/{organization}/passports/{id}/affichageRead the French affichage environnemental state. - get
/organizations/{organization}/importsList import jobs. - get
/organizations/{organization}/imports/{id}Fetch one import job and its progress.
passports:write
- post
/organizations/{organization}/passportsCreate a passport. - patch
/organizations/{organization}/passports/{id}Apply a JSON Merge Patch to a passport. - post
/organizations/{organization}/passports/{id}/publishPublish a passport. - post
/organizations/{organization}/passports/{id}/unpublishUnpublish a passport. - post
/organizations/{organization}/passports/{id}/trashMove a passport to trash. - post
/organizations/{organization}/passports/{id}/restoreRestore a passport from trash. - post
/organizations/{organization}/importsStart an asynchronous bulk import.
No scope required
A valid credential is enough. These endpoints return nothing that belongs to a single tenant.