Agent quick start

Access a protected resource

Use a Service's AEP challenge to authenticate to the requested resource, then retry without changing the request or exposing credentials to another origin.

Start with the requested resource

Suppose the Agent needs GET https://api.example.com/v1/orders/123. This is an application resource, not an Enroll, Grant, or other AEP command endpoint. This example assumes the Agent has an identity the Service recognizes. If it has not established enrollment, follow Enroll an Agent and Check status before expecting access. The Agent also needs to know which Service controls this resource and which authentication method it accepts before sending an AEP credential.

The Agent may first make the exact request without AEP credentials and respond to a live challenge. A fresh, definitive OpenAPI operation match may instead help it plan authentication before the first request; an ambiguous or stale match does not authorize sending credentials and requires live challenge discovery. This example follows the challenge path.

Validate the AEP challenge

A Service protecting this order can respond with 401 Unauthorized and an AEP WWW-Authenticate challenge:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: AEP service_did="did:web:api.example.com",inspect="https://api.example.com/.well-known/aep"

Only an AEP challenge with both service_did and an absolute HTTPS inspect URL begins AEP discovery. An unrelated 401 does not.

Before continuing to discovery, approval, a credential Grant, or an authenticated retry, determine whether the original request body can be reproduced identically. A streamed or otherwise non-replayable body must stop the authentication flow here; a retry with different content would not be the request the caller authorized. The example GET has no body.

Fetch Inspect anonymously in a separate request. Do not copy credentials, cookies, caller authorization, or other headers from the protected-resource request. Require the challenged DID to equal Inspect service.did and verify that the Service DID is bound to the final Inspect origin. Reject a mismatch before requesting an assertion or sending credentials.

Select an advertised method

Inspect authentication.methods lists protected-resource methods in Service preference order. If it is absent or the Agent supports none of the listed methods, stop rather than guessing. Do not infer aep-jwt from the fact that AEP command endpoints accept client assertions, and do not try an unadvertised session credential.

For this example, the Service advertises aep-jwt. The Agent creates a fresh signed client assertion with op=authenticate, aud=did:web:api.example.com, and resource=https://api.example.com/v1/orders/123. An assertion for Enroll, Status, or a different resource cannot authenticate this request. The Identity methods and client assertions page covers the signing and claim rules.

Retry the same request

A generic Agent sends the assertion in Authorization and keeps the original method, target, and body:

GET /v1/orders/123 HTTP/1.1
Host: api.example.com
Authorization: AEP <jwt>

Send at most one AEP credential. If the request also uses MPP or x402, select AEP-Authorization before the first authenticated retry so payment can use its own field; keep that choice throughout the operation. A Service-issued API key instead uses exactly the header selected in its Grant response. Neither authorization field belongs in logs or telemetry.

A valid credential establishes an Agent principal, not permission to read this order. The application may return 403 insufficient_scope after successful authentication. Treat that as a denied application action, not a reason to repeat enrollment or try arbitrary credentials.

Handle redirects without leaking credentials

For a same-origin redirect, follow only if the credential authorizes the new target. With aep-jwt, issue a fresh assertion whose resource identifies that target, and use the same AEP carrier selected for this operation. Do not reuse the order 123 assertion for another order URL.

For a cross-origin redirect, remove AEP assertions, session credentials, Authorization, AEP-Authorization, PAYMENT-SIGNATURE, and any payment credential. Restart at the destination anonymously and require its own valid AEP challenge before authenticating there. Never copy a Service-selected API-key header to another origin. If the request body cannot be replayed identically, stop instead of following the redirect.

Protect a resource: Implement the Service's part of this exchange.
Protected-resource authentication: Read the complete carrier, redirect, and error rules.