Agent Registration
Every agent is a full enterprise identity with a lifecycle, managed the same way an enterprise manages a human workforce identity.
Registering an agent doesn't just create a database row: it provisions an identity with a real state machine, so an agent can be suspended, reactivated, rotated, retired, or revoked, with every transition producing a signed, immutable audit record.
Ownership vs. Principal
owner, business_unit, and environment are organizational labels for who's responsible for an agent (e.g. "Finance Team"). They're separate from acting_for_principal_id, the Principal an agent's actions are evaluated under for policy purposes (e.g. "Finance Manager"). Transferring ownership changes who's responsible for an agent; it never silently changes whose authority it acts under. Authority comes from the Principal, which comes from the organization, never from the agent itself.
The state machine
registered -> active -> suspended -> active -> retired
\-> revoked
registered ---------------------------------> retired
registered ---------------------------------> revoked| State | Meaning | Can sign actions? |
|---|---|---|
| registered | Exists, not yet operational. | No |
| active | Fully operational. | Yes |
| suspended | Temporary lock. | No, but reviewable |
| revoked | Certificate permanently revoked. Terminal. | No, ever |
| retired | Permanently removed from operational use. Terminal. | No, ever |
Revoking and retiring are both reachable from registered, active, or suspended: a compromised key doesn't wait for the agent to be active first.
Registering directly against the API
The Operator Key below is a platform-internal, administrative credential, not something a new external developer is issued. A sandbox or scoped organization API key (see Getting Started) authenticates the identical endpoint via a standard Authorization: Bearer header instead.
curl -X POST https://api.aisecurewatch.com/v1/agents \
-H "X-PayReality-Operator-Key: your-operator-key" \
-H "Content-Type: application/json" \
-d '{
"name": "AP Automation Agent",
"acting_for_principal_id": "<principal_id>",
"public_key": "ed25519:base64:<your-agents-public-key>"
}'A newly created agent starts registered, not active: an account is provisioned, then a separate step enables it, the same two-step flow a real enterprise identity system uses, with room for a human approval gate between the two if you want one.
curl -X POST https://api.aisecurewatch.com/v1/agents/{agent_id}/activate \
-H "X-PayReality-Operator-Key: your-operator-key"The Python SDK's register() chains this activation call automatically, so it hands back a ready-to-use, active identity in one call. See SDKs.
What happens in each non-active state
A revoked or retired agent's actions are rejected before anything is recorded: these are terminal states with no standing to act at all. A suspended agent's action is recorded and immediately sent to Human Review rather than evaluated against any rule, since suspension is temporary and reviewable: what was attempted while suspended is preserved, not silently dropped.