Authentication
API keys, sessions, permissions and scope.
Credentials
| Credential | Looks like | Header |
|---|---|---|
| API key | pap_… | X-API-Key: pap_…, or Authorization: Bearer pap_… |
| User session | pus_… | Authorization: Bearer pus_… |
| Single sign-on | A JWT from your identity provider | Authorization: Bearer <jwt> |
API keys are for software. Sessions are what a person gets by signing in, and are what the console uses. Where both are present on a request, X-API-Key wins.
A key is shown exactly once, in the response that creates it. There is no way to read it back afterwards — if it is lost, revoke it and make another.
Scope
Every credential belongs to one account and reaches some or all of the companies under it.
- A key created with
companyIdreaches that company only. Ids belonging to other companies answer404 NOT_FOUND, identical to ids that do not exist, so a scoped key cannot be used to discover what else the account contains. - A key created without
companyIdreaches every company under the account. Only an account owner can create one.
When a credential reaches several companies, a request about one of them has to say which — companyId in the body or the query string — or it is refused with 400 COMPANY_REQUIRED. Nothing is guessed. Sending is the exception: the sender participant already determines the company.
Permissions
An API key carries any of four permissions:
| Permission | Allows |
|---|---|
read | Reading the account, messages, participants, usage |
send | Submitting documents and requesting uploads |
receive | Acknowledging inbound documents |
manage | Users, companies, keys, webhooks, capabilities, SFTP |
Omitted or empty at creation means all four. Calling a route the key lacks the permission for is 403 PERMISSION_DENIED.
Issue the narrowest set that works. An integration that only pushes invoices needs send, and possibly read to check on them — it does not need manage, which would let it create further keys.
Roles
A user, as opposed to a key, has a role:
| Role | Reaches |
|---|---|
| Owner | Everything under the account, including users, keys, companies and single sign-on |
| Company admin | One or more named companies, including their keys, webhooks and SFTP logins — but nothing account-wide |
| Member | The companies they are assigned to, without administration |
Owner-only actions are the ones that change who has access: creating and removing users, keys and webhooks, adding companies, linking single sign-on, exporting account data, and resetting SFTP passwords. A company admin can do those within its own companies; account-wide credentials stay invisible to it.
Permissions apply to keys, not to sessions. A user is limited by their role and their company scope instead.
Sessions
Signing in returns a pus_ session token. Sessions are long-lived but not permanent, and signing out ends one immediately.
A user who must change their password can reach only their own profile until they do; everything else answers 403 PASSWORD_CHANGE_REQUIRED.
Single sign-on
Where it is configured for an account, an OIDC token from the account's identity provider is accepted in place of a session. Identities are linked per user, and a linked identity can be removed without deleting the user.