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. This is a practical instance of a broader Zero Trust principle the runtime follows throughout: no caller, agent or human, is trusted by network position or prior request: every request authenticates on its own merits, every time.
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. Key rotation never invalidates history: decisions made under a previous certificate remain exactly as valid as they were, since the certificate that was active at the time is what's recorded, not the agent's current one.
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 permission check, 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.
The Operator Key belongs to no single organization. For any endpoint that acts on behalf of a specific organization, such as verifying a Capability Authorization, it must also name which one, via X-PayReality-Organization-Id: without that header the request is rejected, and with it, the Operator Key is scoped to that organization exactly like any other credential. It doesn't grant standing access to every organization at once.
Roles and permissions
For organizations with more than one person operating the platform, six fixed roles each map to a fixed set of permissions:
| Role | Can |
|---|---|
| Organization 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.
"Review AI-extracted authority" in the table above is deliberately a human permission, not something the AI Authority Builder grants itself: AI proposes a structured authority graph from a governance document, it never grants authority or activates a policy on its own. Citations and critical values are checked deterministically against the source document; a Governance Administrator or Reviewer still has to confirm the identities and relationships it proposed before anything compiles. A high-risk change also needs a separate accountable actor from whoever proposed it, a maker-checker split, not a single person's approval, and only an approved, versioned revision ever compiles and activates. See Authority Graph for what that compiled structure looks like.
Per-developer API keys
For an integration that shouldn't hold full administrative power, a scoped, role-bound API key can be issued from Organization 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.