Authentication
Four distinct credentials, each authenticating a different kind of caller: an agent, an administrator, a specific human, or a specific integration.
PayReality never checks a role directly to decide whether a request is allowed. Every administrative endpoint checks a specific permission, and a permission is granted by exactly one of four credentials, layered so the simplest one (a single shared key) never has to be replaced before a real multi-user rollout needs the others.
Agent certificates
Every registered agent gets its own ED25519 key pair, generated client-side; only the public key is ever sent to PayReality. Every action an agent submits is signed over the raw request body with its private key, so the platform can verify a request genuinely came from that specific agent and hasn't been altered in transit:
X-PayReality-Key-Id: <certificate_id>
X-PayReality-Signature: <ed25519 signature over the raw request body>If an agent is compromised or decommissioned, its certificate is rotated or revoked, immediately cutting off its ability to act, the same way deactivating an employee's badge does.
The Operator Key
A single shared administrative credential, sent as X-PayReality-Operator-Key. A present, correct Operator Key is a full bypass on every administrative endpoint, the original and simplest way to authenticate as a trusted administrator. Every SDK example on this site that needs administrative access (registering an agent, publishing a rule) uses it.
Roles and permissions
For organisations with more than one person operating the platform, six fixed roles each map to a fixed set of permissions:
| Role | Can |
|---|---|
| Organisation Owner | Everything: every permission in the system. |
| Governance Administrator | Create, edit, and publish Runtime Policies; review AI-extracted authority. |
| Agent Administrator | Register, suspend, rotate, and retire agents. |
| Reviewer | Review AI-extracted authority; approve or reject. Cannot publish. |
| Auditor | Read-only: evidence, decisions, policies, agents, assurance. |
| Executive | Read-only assurance dashboards. |
A person authenticates by logging in and sending the resulting session token as a bearer token: Authorization: Bearer <token>. The token is the session's own identifier, not a JWT, so revoking a session is instant.
Per-developer API keys
For an integration that shouldn't hold full administrative power, a scoped, role-bound API key can be issued from Organisation Settings. It authenticates the same way a session does (Authorization: Bearer <key>), resolves to a role, and is shown exactly once at creation time.
How they layer
On every administrative request, the Operator Key is checked first: if present, it decides the outcome immediately, correct or not, exactly as it always has. Only when no Operator Key is sent does the platform fall back to resolving a bearer token (a session or an API key) to a role, then checking that role's permissions against what the endpoint requires. Existing integrations built against the Operator Key are never affected by the existence of the other three credentials.