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.

Keep document acceptance in the Owner's decision

A Service can also advertise required documents. For example, the Owner reviews the HTML links for general-terms and product-terms and approves that original ID list in one decision. The Agent sends those IDs in acknowledged_document_ids with Enroll, alongside any authorized claims. Reading a document alone does not accept it.

If another document appears while approval is pending, do not silently add it to the approved list or reject an otherwise valid declaration just for omitting it. The Service can report it as an unmet requirement on a later Grant. The caller then explicitly repeats Enroll and, afterward, Grant.

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.