Protected discovery

What the Service advertises

The example Service Document declares authentication required for all three advertised Offering operations. It advertises AEP for enrollment and identifies two supported payment protocols in preference order. These declarations prepare an Agent for likely access requirements; they do not replace a live challenge.

Payment-option names are human-readable compatibility labels. They do not define the exact method, network, asset, amount, or settlement terms; the selected payment protocol supplies those details in its live challenge.

Begin with the requested operation

The Agent starts by calling the ODP operation the caller selected in its current authentication context. It does not enroll or pay solely because the Service Document advertises those protocols. For this protected Service, a request without acceptable AEP credentials receives an AEP challenge.

GET /odp/offerings HTTP/1.1
Host: catalog.example

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

The 401 response identifies the Service DID and its AEP inspection document. The Agent follows the AEP flow, obtains an acceptable credential, and retries the same ODP operation. A public operation could instead return its ODP representation immediately, and a payment-only operation could return a 402 response without AEP.

Authenticate before paying

When an operation requires both authentication and payment, the Service authenticates the Agent first. This example assumes the AEP Inspect document advertises aep-jwt for protected-resource authentication. A Service that advertises a session credential method uses that method's defined credential presentation instead.

For MPP, the Agent carries its AEP assertion in AEP-Authorization so Authorization remains available for the MPP payment credential. The authenticated request receives a complete Payment challenge in WWW-Authenticate:

GET /odp/offerings HTTP/1.1
Host: catalog.example
AEP-Authorization: AEP <client-assertion>

HTTP/1.1 402 Payment Required
Cache-Control: no-store
WWW-Authenticate: Payment id="qB3wErTyU7iOpAsD9fGhJk", realm="catalog.example", method="inflow", intent="charge", request="eyJhbW91bnQiOiIxMC41IiwiY3VycmVuY3kiOiJVU0RDIiwibWV0aG9kRGV0YWlscyI6eyJyYWlsIjoiYmFsYW5jZSJ9LCJyZWNpcGllbnQiOiIxMTExMTExMS0xMTExLTExMTEtMTExMS0xMTExMTExMTExMTEifQ"

After the caller approves payment, the Agent retries with the MPP credential and a newly generated AEP JWT assertion. The new assertion needs its own jti and must be bound to this protected-resource request; an assertion accepted on the challenge request cannot be replayed. The successful response includes the recommended Payment-Receipt.

GET /odp/offerings HTTP/1.1
Host: catalog.example
AEP-Authorization: AEP <new-client-assertion>
Authorization: Payment <payment-credential>

HTTP/1.1 200 OK
Cache-Control: private
Payment-Receipt: <MPP payment receipt>
Content-Type: application/odp+json

For x402, the authenticated request receives encoded payment requirements in PAYMENT-REQUIRED:

GET /odp/offerings HTTP/1.1
Host: catalog.example
AEP-Authorization: AEP <client-assertion>

HTTP/1.1 402 Payment Required
Cache-Control: no-store
PAYMENT-REQUIRED: <x402 payment requirements>

After the caller approves payment, the Agent retries with the x402 payment proof and another newly generated, request-bound AEP JWT assertion. A successful x402 response includes the encoded settlement result in PAYMENT-RESPONSE.

GET /odp/offerings HTTP/1.1
Host: catalog.example
AEP-Authorization: AEP <new-client-assertion>
PAYMENT-SIGNATURE: <x402 payment signature>

HTTP/1.1 200 OK
Cache-Control: private
PAYMENT-RESPONSE: <x402 settlement response>
Content-Type: application/odp+json

Never copy an AEP assertion, session credential, MPP credential, or x402 payment proof to another origin. Redirects and retries remain subject to each protocol's request-binding and replay rules.

Let the live response determine the next step

The Service Document describes supported protocols and expected access requirements. The response to the current operation is authoritative for whether that request needs authentication or payment and for the exact retry mechanics. Apply these rules directly:

Apply each protocol to its part of the exchange

ODP connects discovery to later protocol exchanges without redefining them. The Service implementation and Agent apply the specification that owns each live signal.

Inspect the example artifacts

The generated artifact contains the complete Service Document used by this example. Compare its protocol descriptors and operation access declarations with the request sequence above.

• Generated example: open the published protected-discovery example and its source files
• Service Document JSON: inspect the enrollment, payment, and authenticated-operation declarations

Next steps