[a]authored byinflow
Agent quick start

Enroll an Agent

Introduce your Agent identity to a Service, submit the information you are authorized to share, and act on the Service's enrollment decision.

What Enroll asks the Service to do

An AEP Service does not recognize an Agent merely because the Agent has a valid identity. Enroll asks the Service to associate that identity with its own enrollment record and decide whether the Agent is active, pending further work, or rejected. The Service may ask for claims or Owner action before it recognizes the Agent.

Start here only after you have inspected the Service. This page follows the example Service at https://api.example.com: it advertises Enroll and Status, accepts did:web Agent identities, and requests contact.email. Enrollment does not by itself authorize every protected application request.

Prepare the identity and claim

Use an Agent DID that the Service can verify through an identity method it advertised. Confirm that your signing key uses one of its core.signing_algorithms values. Ask the Agent's Owner for a contact.email value it authorizes you to submit. Do not invent a value or assume the Service will treat submission as verification. If the required value is unavailable, seek it before Enroll or decide not to proceed. A request missing a required claim can fail with 422 requirements_unmet; if the Service accepts the request, it reports its enrollment decision in a lifecycle response.

Create a fresh client assertion for this Enroll call. Its iss and sub identify your Agent DID, aud is the service.did from Inspect, and op is enroll. The DID portion of kid identifies the same Agent. The assertion also needs a short validity window and a fresh jti. See Agent identity and assertions for signing and key-hosting details.

Send one Enroll request

Send POST to the Enroll path derived from the inspected http.endpoint_base. With the example base of /aep/, that path is /aep/enroll. Include the signed assertion, a non-empty Idempotency-Key header, and a JSON body naming the same Agent DID as the assertion.

POST /aep/enroll HTTP/1.1
Host: api.example.com
Content-Type: application/aep+json
Authorization: AEP <jwt>
Idempotency-Key: 9f8a4d2e-1c3b-4f5e-8b7a-000000000000

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

The example claim value is illustrative; send only a value your Agent is authorized to disclose. The body can also include idempotency_key when your integration needs it there, but if both forms are present, the body value must match the header. Use the baseline client assertion for Enroll; obtaining a session credential is a later, optional step.

Read the immediate result

A successful Enroll response uses 200 OK and a lifecycle status. For a new enrollment, active means the identity is enrolled and operational; pending means the decision awaits further work; rejected means the initial decision did not approve it. Do not treat pending as an HTTP error or assume active grants permission for every application resource.

For example, the Service may still be verifying the submitted email while also requiring an out-of-band action by the Agent's Owner:

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

verification_pending names a submitted claim awaiting verification; it does not contain the email value. requirements_pending, when present, names a requirement still to be satisfied. owner_action_required is independent of both lists. If enrollment is pending and Status is advertised, use Check status to learn when the state changes; arrange Owner action separately when indicated. If the initial response is rejected, stop this attempt rather than polling for it to become active.

Retry safely if the response is lost

If the network fails after you send Enroll, the Service may already have processed it. Retry with the same Agent, command, request body, and Idempotency-Key. Sign a fresh assertion with a new jti for the retry. The Service returns its cached response or an equivalent successful response when that key still identifies the same request. Reusing the key with a different body or command is a conflict.

A later Enroll call with a new key is not a way to update or renew enrollment. If the Agent already has a record, the Service returns its current lifecycle state without replacing it. The Enroll and Status page covers the exact response and retry rules.

Choose the next step

For a pending result, follow Check status and respond to any separate verification, missing requirement, or Owner action. For an active result, the Agent may attempt a protected operation if the Service advertises an authentication method for it; Access a protected resource explains that separate authentication and authorization step.

On this page