OpenAPI authentication mapping

Find and fetch the OpenAPI document

A Service may advertise http.openapi in its Inspect document so Agents can identify an operation's authentication requirements before calling it. OpenAPI is optional planning information for protected resources, not an AEP command or permission to use the resource. The example Service also advertises aep-jwt and oauth-bearer in Inspect authentication.methods. Its OpenAPI advertisement can point to the document like this:

"openapi": {
  "path_matching": {"trailing_slash": "strict"},
  "url": "/openapi.json"
}

Resolve a relative url against the final Inspect response URL. An absolute HTTPS URL may be on another origin. Plain HTTP is permitted only for the syntactic loopback hosts localhost, 127.0.0.1, and [::1] during development; do not treat a different hostname as loopback merely because it resolves there. Reject user information in the URL and HTTPS-to-HTTP downgrades.

Fetch the document anonymously. Do not copy resource credentials, AEP assertions, Platform credentials, cookies, caller authorization, or any other headers from the triggering request. Set bounds on redirect count, decoded response size, and total fetch time; a cross-origin HTTPS redirect can be followed only while the fetch stays anonymous and within those bounds. Reject partial or over-bound content.

Accept OpenAPI 3.1 JSON served as application/json or application/vnd.oai.openapi+json with a version=3.1 parameter. Valid extra media-type parameters do not change that decision. A missing or malformed content type, a non-JSON body, or an openapi version outside the 3.1.x family is not a usable mapping.

Match the requested operation

For GET https://api.example.com/v1/orders/123?include=items, use the uppercase method GET and the path /v1/orders/123 to select an OpenAPI operation. A template such as /v1/orders/{orderId} can match; the query string does not select the operation. A literal path segment takes precedence over a template segment.

Inspect http.openapi.path_matching.trailing_slash determines whether /v1/orders/123 and /v1/orders/123/ are distinct. strict keeps them distinct; equivalent ignores exactly one terminal slash except at /. Multiple equally applicable templates or structurally equivalent templates with different variable names make the match ambiguous. Do not choose credentials from an ambiguous operation.

Read the operation's security requirement

OpenAPI security at the document root applies unless an operation defines its own security value. The operation value replaces the root value; it does not add to it. This example document uses an OAuth Bearer session credential at the root but allows either an AEP assertion or that credential for an order lookup:

{
  "openapi": "3.1.0",
  "info": {"title": "Example Service", "version": "1.0.0"},
  "components": {"securitySchemes": {
    "agentAssertion": {"type": "http", "scheme": "AEP",
      "x-aep-authentication-method": "aep-jwt"},
    "serviceToken": {"type": "http", "scheme": "bearer",
      "x-aep-authentication-method": "oauth-bearer"}
  }},
  "security": [{"serviceToken": []}],
  "paths": {
    "/v1/orders/{orderId}": {"get": {
      "security": [{"agentAssertion": []}, {"serviceToken": []}]
    }},
    "/health": {"get": {"security": []}},
    "/optional": {"get": {"security": [{}, {"agentAssertion": []}]}}
  }
}

The two objects in the order operation's security array are alternatives: either complete object can satisfy the operation. /health replaces the root requirement with an empty array and is public. /optional has an empty object as one alternative, so anonymous access is permitted there. Two scheme names inside one object instead form a compound requirement; the Agent must satisfy both or choose another complete alternative. It must not silently drop one scheme.

The scheme names agentAssertion and serviceToken are local OpenAPI names. Their x-aep-authentication-method values bind them to aep-jwt and oauth-bearer. A security scheme without that extension is not an AEP method merely because its name or HTTP scheme looks familiar. The Agent still needs a method it supports and the Service advertises for protected resources.

Use the mapping or ask the live Service

A fresh, definitive operation match may be used to plan authentication without first probing the resource. If it permits anonymous access, send no AEP credential on that basis. If it requires authentication, choose a complete supported alternative before sending a credential. A mapping never authorizes the request; the Service still authenticates and applies its application policy.

Keep the Service trust boundary

The OpenAPI document describes operations; it does not establish which origin controls the Service DID. Verify the Service DID against the final Inspect origin before provisioning identity material, requesting an assertion, or transmitting credentials. An OpenAPI URL on another HTTPS origin does not move that trust boundary.

OpenAPI also does not relax protected-resource redirect rules. A same-origin redirect may need a newly bound assertion; a cross-origin redirect strips AEP and payment credentials and begins anonymously at the new origin. Continue to Protected-resource access for the complete Agent request path, or Protected-resource authentication for the credential and challenge rules.