Guide

Protected-resource access

Build an Agent request path that can authenticate a protected operation without changing its body, guessing at credentials, or forwarding secrets across origins.

Preserve the caller's operation

The Agent's job is to complete the operation the caller requested, not to turn an authentication challenge into a different operation. Consider this illustrative request to a protected Service resource:

POST /v1/reports HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 23

{"report_type":"usage"}

Keep the method, absolute target, relevant headers, and exact body available for an authenticated retry. Before AEP discovery, approval, a credential Grant, or retry, determine whether the body can be reproduced identically. An in-memory JSON body can be retained; a one-shot stream may not be replayable. If the body cannot be reproduced, stop before starting the authentication flow rather than send a different report request. If an enforced cancellation, time, or size limit is reached, stop without processing partial authentication metadata.

Determine what this resource requires

A fresh, definitive OpenAPI match for this method and path may let the Agent plan authentication before sending the resource request. Fetch OpenAPI anonymously, without copying caller credentials, cookies, or other headers. If the operation is undocumented, the mapping is ambiguous or unsupported, or the document is stale or contradicts a live response, fall back to an anonymous request and live challenge discovery. OpenAPI does not itself authorize access.

On the challenge path, only 401 Unauthorized with an AEP WWW-Authenticate challenge containing service_did and an absolute HTTPS inspect URL starts AEP discovery. An unrelated 401 does not. Fetch Inspect anonymously, require the challenged DID to match service.did, and verify the DID's binding to the final Inspect origin before obtaining or transmitting credentials. The Access a protected resource quick start shows this first exchange.

Choose a method the Agent can present

A definitive OpenAPI operation match may permit anonymous access; in that case, send the request without AEP credentials. Otherwise, satisfy one complete security requirement alternative. Do not discard part of a compound requirement merely because one method appears in Inspect. An unsupported mapping falls back to live challenge discovery, not a guessed partial credential.

Inspect authentication.methods lists protected-resource methods in Service preference order. After a valid challenge, choose one the Agent supports and that the resource accepts. If none is usable, stop. The baseline client assertion accepted by AEP command endpoints is not an automatic fallback for protected resources.

For aep-jwt, issue a fresh assertion with op=authenticate, aud equal to the Service DID, and resource equal to the normalized absolute target of the report request. An Enroll or Status assertion cannot authenticate it. A registered session-credential method can instead use an existing credential only when its grant type is advertised and that credential is valid for this request; obtain one through Grant only when needed and supported. The Protected-resource authentication page defines the precise assertion and carrier rules.

Keep authentication and payment separate

A generic Agent places an authorization-carried AEP credential in Authorization. When the same operation also uses MPP or x402, select AEP-Authorization before the first authenticated retry and keep that selection for the operation. It preserves Authorization or PAYMENT-SIGNATURE for the payment protocol. Send only one AEP credential carrier; do not put an AEP credential in both authorization fields.

An AEP-issued API key follows its Grant response instead: send it in the exact Service-selected header, not as an alternate form of the JWT. Treat authorization fields and API-key headers as secrets; do not copy them into logs, cache keys, or unrelated requests. If the resource also charges for access, AEP authentication establishes the Agent first and payment processing follows. AEP does not decide whether payment succeeds.

Retry, stop, or restart deliberately

An authenticated retry keeps the original POST target and body. The response then determines whether the Agent has completed the operation, must stop, or must begin a new trust decision. Do not loop over methods or replay a rejected credential without a reason grounded in the Service response.

Response or event	Agent action
Valid initial AEP challenge	Verify the Service, select an advertised method, and retry only if the request is reproducible.
401 not_recognized	Do not replay the same credential. Re-evaluate identity or credential state; the error deliberately does not identify which recognition check failed.
403 insufficient_scope	Stop. Authentication succeeded, but the application denied this action. Re-enrollment is not an authorization remedy.
Same-origin redirect	Follow only when the credential authorizes the new target. For aep-jwt, sign a new target-bound assertion in the same carrier.
Cross-origin redirect	Strip AEP and payment credentials, restart anonymously at the new origin, and require its own valid challenge. Stop if the body cannot be replayed.

On a cross-origin redirect, stripping includes Authorization, AEP-Authorization, PAYMENT-SIGNATURE, session credentials, and the Service-selected API-key header. A fresh challenge at the destination does not make a credential from the first Service valid there. For the exact error and redirect contract, use Protected-resource authentication.