Authentication
Authentication
A secret key in the Authorization header is how you reach your own records. There is no other way in, and no request is ever authenticated by a session cookie. The category endpoints are the exception: they describe the fields we ask for rather than anybody's data, and they answer without a key.
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 your real passports. 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 of your records.
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}/publish-approvals/{id}Fetch one publish approval. - 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.
No credential required
Readable without a key. These endpoints describe the product itself — which categories exist, and which fields each one asks for — so the answer is the same for every reader. A key is still accepted, and one that has been revoked or has expired is still refused. Without a key you are measured against the anonymous counter of 60 requests a minute per client address.