Integration Examples

Everything below uses the Python SDK, but it's a convenience wrapper, not the only way in: any agent runtime, gateway, or customer-controlled enforcement point that can call the same underlying endpoints directly participates in the same vendor-neutral authority contract without this SDK at all. See Architecture for that contract, and Runtime API for the raw calls.

Register once, use everywhere

from payreality import Agent

agent = Agent(bearer_token="pr_live_...")  # a sandbox or scoped org API key; the Operator Key also works
identity = agent.register(name="AP Automation Agent", principal="Finance Manager")
# identity.status == "active": ready to sign Intents immediately

Registering an agent through the raw API leaves it in a registered state until a separate activation step runs, the same two-step provisioning a real enterprise identity system uses. The SDK's register() chains that activation automatically, so it still hands back a ready-to-use identity in a single call: a minimal SDK integration, not a two-step provisioning flow you have to reason about yourself.

Rotating an agent's key

new_identity = agent.rotate_keys()
print(new_identity.certificate_id)  # the new certificate's ID

Generates a new key pair locally, uploads only the new public key, and switches this agent to sign with it from this point on. The previous private key is discarded the moment this call returns. Every decision made before rotation stays exactly as valid as it was: rotating a key never invalidates history.

Heartbeat

agent.heartbeat(version="1.4.0", runtime="Azure Foundry")

Reports this agent as alive. Unlike the other lifecycle calls, a heartbeat is signed with the agent's own certificate, not the Operator Key: it's the agent asserting its own liveness, not an administrative action. All parameters are optional; call it however often makes sense for your deployment.

Retiring an agent

agent.retire(reason="decommissioned, replaced by v2")

A server-side, terminal action, not a local flag: once retired, no process signing with this identity's key can submit Intents or heartbeats again, and historical Evidence is unaffected. Calling authorize() again on an Agent your own process just retired fails immediately, without a network round trip.

Reporting an execution receipt back EARLY ACCESS

If your enforcement point or trusted execution adapter is the separately authenticated identity that actually carried out an authorized action, it can report that back so PayReality can reconcile what happened against what it authorized. This is newer than the rest of this page and not yet part of the stable public SDK surface; treat the call below as illustrative:

# Called by your trusted execution adapter, not the requesting Agent itself
result = adapter.report_execution(
    decision_id=decision.decision_id,
    status="completed",
    details={"transaction_id": "txn_88f1e2"},
)

print(result.reconciliation_status)  # MATCHED, MISMATCHED, EXECUTION_FAILED,
                                      # PARTIAL, RECEIPT_MISSING, or INDETERMINATE

A cryptographically authenticated execution receipt proves what the trusted source reported. It does not independently prove that the underlying business system or real-world event was truthful. See Runtime API for the current shape of reconciliation, and Authorization Receipts for how it fits into the wider evidence record.