Integration Examples

Register once, use everywhere

from payreality import Agent

agent = Agent(api_key="your-operator-key")
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 one call: the "install and start using in under five minutes" experience the SDK was built for.

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.