Claims and approval

What this Service requires

In this example, api.example.com asks for the Agent Owner's contact email. Its policy also requires the Owner to complete a separate out-of-band approval step. The Service will not treat the submitted email as verified merely because its syntax is valid. The particular verification and approval procedures belong to this example Service; AEP defines how their outstanding state is reported, not how those procedures are carried out.

Assume the Agent has already inspected this Service and confirmed that it advertises Enroll and Status and accepts the Agent's identity method. The exchange below concentrates on the claim and lifecycle response. Enroll an Agent covers assertion signing and the complete request procedure.

The Service lists contact.email under claims.required in its Inspect document. This tells the Agent what value the Service needs for enrollment before the Agent sends personal data:

"claims": {
  "required": ["contact.email"],
  "preferred": [],
  "optional": []
}

This is only the claims fragment, not a complete Inspect document. The Claims and verification guide explains how a Service chooses required, preferred, and optional claims.

After the Owner authorizes disclosure of ops@example.com, the Agent sends it in the Enroll claims object. The request identifies the Agent DID, presents an operation-bound client assertion, and carries a non-empty idempotency key:

POST /aep/enroll HTTP/1.1
Host: api.example.com
Content-Type: application/aep+json
Authorization: AEP <jwt>
Idempotency-Key: 6b7cb1d8-6180-48f3-9d3b-bd9efcd80601

{
  "agent_did": "did:web:agent.example.com:agents:123",
  "claims": {
    "contact.email": "ops@example.com"
  }
}

The submitted address is an assertion from the Agent or Owner. It is not evidence that the mailbox is controlled by either of them. The Service must make its own policy decision about whether verification is necessary and how to perform it.

The Service accepts the Enroll request with 200 OK but has not completed enrollment. It is verifying the submitted email and separately waiting for Owner approval:

{
  "owner_action_required": "true",
  "status": "pending",
  "verification_pending": ["contact.email"]
}

verification_pending names the submitted claim still under review; it does not repeat the email value. owner_action_required tells the Agent that its Owner has something to do outside this AEP response. It does not specify the approval channel or create an AEP approval command. requirements_pending is absent because this example does not have an unmet requirement to report.

The Agent should tell its Owner that the Service requires action and use the Service's separate instructions for completing it. It should not repeatedly submit the email or retry Enroll in an attempt to clear these fields.

The Agent calls the advertised Status command with a fresh assertion bound to status. While verification and Owner action are still outstanding, a successful 200 OK response can continue to report them:

{
  "owner_action_required": "true",
  "since": "2026-06-28T12:00:00Z",
  "status": "pending",
  "verification_pending": ["contact.email"]
}

After the Service verifies the email and the Owner completes its separate action, a later Status response can report an active enrollment:

{
  "since": "2026-06-28T12:05:00Z",
  "status": "active"
}

The example since values mark the last state transition. The active response has no pending lists or Owner-action flag because this Service has finished those steps. Status reads the existing record; it does not submit a replacement Enroll request. active means the identity is operational at this Service, but application authorization for a protected resource remains a separate decision.

For the full meaning of the lifecycle states and pending fields, read Enrollment lifecycle and Owner action.