[a]authored byinflow
Protocol

Publish and read the Inspect document

The Service advertises its AEP capabilities at a fixed well-known path. The Agent checks that document before using an authenticated command or sending credentials.

What Inspect tells an Agent

The Inspect document is a Service's public AEP advertisement. It tells an Agent which Service it is talking to, which enrollment commands exist, which Agent identities the Service accepts, and what information may be requested. The Agent reads it before creating a Service-specific identity or sending an authenticated command.

Inspect is a starting point, not a promise that an individual Agent will be enrolled or allowed to use a protected resource. The Agent must verify that the document belongs to the Service origin, then follow only the capabilities it advertises. The Service remains responsible for its enrollment and resource-access decisions.

Fetch Inspect

The Service serves an unauthenticated GET /.well-known/aep response at its origin. A successful response carrying the Inspect document uses Content-Type: application/aep+json. The Agent can request that type with an Accept header, but it must check the response type rather than assume the body is AEP JSON.

The AEP HTTP binding uses TLS 1.3 or later for network requests. Inspect needs no Agent assertion or session credential. A missing, malformed, or different successful-response media type is not a usable Inspect document; valid media-type parameters do not change the application/aep+json essence.

Read the advertisement

This example advertises Inspect, Enroll, and Status but no session-credential commands or protected-resource authentication method. The Service DID is for the origin https://api.example.com.

{
  "aep_version": "1.0",
  "bindings": {"supported": ["http"]},
  "commands": {"supported": ["inspect", "enroll", "status"]},
  "core": {"signing_algorithms": ["EdDSA", "ES256"]},
  "http": {"endpoint_base": "/aep/"},
  "identity": {"methods": ["did:web"]},
  "service": {"did": "did:web:api.example.com"}
}

Every Inspect document contains a protocol version, supported bindings and commands, signing algorithms, HTTP configuration, accepted Agent identity methods, and the Service DID. commands.supported always includes inspect. If the Service exposes an authenticated command, it advertises at least one identity.methods value.

A Service can also advertise requested claims and protected-resource authentication methods. The claims object separates required, preferred, and optional claim names. authentication.methods lists methods accepted by protected application resources; if absent, the Service advertises none. It does not change the baseline client-assertion requirement on exposed AEP command endpoints.

An Agent processes a supported AEP version and only the capabilities the document advertises. The Versioning and extensibility page covers unknown fields, identifiers, and compatible versions.

Construct command URLs

Inspect is always at the well-known path. Other AEP command paths are relative to http.endpoint_base. If that field is absent, the Agent uses /aep/. Append the command path with exactly one slash: both /aep and /aep/ yield /aep/enroll.

The Agent invokes only commands listed in commands.supported. Grant and Revoke can be advertised only when commands.grant_types contains a supported session-credential format. authenticate is not a command endpoint and must not appear in the supported-command list.

Verify Service identity

The service.did value identifies the Service and becomes the audience of Agent client assertions. For a did:web Service, the HTTPS origin encoded by that DID must match the origin of the final Inspect response URL. DID path components do not change that origin.

The Agent rejects a mismatch before it provisions identity, requests a signature, or sends credentials. A Directory listing does not replace this check. An Agent using another Service DID method needs an equivalent origin-control binding; it cannot accept an unverified relationship between the document and the Service origin.

Fetch safely and keep the document current

An Inspect redirect may stay within the same scheme, host, and effective port. The Agent rejects a cross-origin redirect or a scheme downgrade. It checks the final response's media type and Service identity before relying on the document.

The Service should send cache metadata such as Cache-Control and ETag. A 300-second default freshness period is recommended when the Service does not need a shorter one. The Agent honors usable cache metadata, including conditional revalidation and 304 Not Modified. no-cache requires revalidation before reuse; no-store prohibits reuse after the current fetch.

An Agent may set documented bounds on decoded response size and total completion time. If it does, an exceeded bound fails closed; the Agent must not use a partial document. These checks belong to Inspect retrieval, before any authenticated command begins.

Optional OpenAPI advertisement

The optional http.openapi member points to an OpenAPI 3.1 document for protected Service resources. It does not replace the Inspect document or make a protected operation accessible by itself. See OpenAPI authentication mapping for retrieval, operation matching, and how an Agent selects an advertised authentication method.

Next steps

On this page