[a]authored byinflow
Protocol

Versioning and extensibility

The AEP version tells an Agent whether it can read a Service's Inspect document. The advertisements inside that document tell it which commands, identity methods, credentials, and extensions it can actually use.

Read the version before the capabilities

aep_version is a JSON string in MAJOR.MINOR form. Both parts are unsigned decimal integers without leading zeroes, except 0 itself. This core draft defines 1.0. The major number identifies a compatibility family: an implementation must reject an Inspect document with a major version it does not support.

Within a supported major family, an implementation processes any minor version using the unknown-field and extension rules below. A minor revision can add optional fields, values, and capabilities or clarify existing behavior. It cannot remove or redefine existing wire behavior or make a new capability mandatory for implementations of an earlier minor revision. aep_version is the version authority; an HTTP media-type parameter does not select another AEP version.

Do not infer a capability from the version

A Service with a compatible version is not automatically a Service that supports Grant, a particular Agent identity method, API-key authentication, or an extension. Check commands.supported before invoking a command, identity.methods before choosing an identity method, commands.grant_types before requesting a session credential, and authentication.methods before authenticating to a protected resource.

For example, imagine a future 1.1 Inspect document. The excerpt below is hypothetical and omits other required Inspect fields; it is not a published version or a complete Service document:

{
  "aep_version": "1.1",
  "commands": {
    "supported": ["inspect", "enroll", "future-command"]
  },
  "extensions": {
    "supported": ["https://example.com/aep/extensions/future"]
  },
  "identity": {
    "methods": ["did:web", "future-method"]
  }
}

An Agent that supports major version 1, did:web, and Enroll can use those understood parts. It ignores future-command, future-method, and the unfamiliar extension URI; it does not invoke the command or pretend to support the method or extension. Nothing about 1.1 alone changes those decisions.

Ignore unknown additions without guessing their meaning

Agents ignore extension identifiers, additive fields, and syntactically valid advertised list values they do not understand. Ignoring an unknown command means not calling it. Ignoring an unknown grant type or authentication method means not using it. A Service may advertise a required claim the Agent does not know how to provide; the Agent can decline enrollment under its local policy rather than inventing a value or assuming the requirement is optional.

These rules protect compatibility when a Service adds an optional capability. They do not authorize an Agent to ignore a known security requirement, reduce an OpenAPI compound requirement, or treat an unfamiliar extension as equivalent to one it understands. Read Discovery and Inspect for the full Service document and retrieval rules.

Advertise an addition in the field that defines it

extensions.supported lists extension identifiers. identity.methods lists identity methods accepted for authenticated commands. commands.grant_types lists session-credential formats the Service can issue and revoke, and commands.grant_types_config carries their advertised configuration. claims.required, claims.preferred, and claims.optional can name claims from the AEP registry or another document. Future documents may add top-level Inspect fields.

A new grant type needs its own definition of the request and response fields, HTTP presentation, expiry, revocation, and any additional errors. An extension may add behavior but cannot redefine a core command, field, status value, or error code. The Service advertises support explicitly so an Agent can choose only what it understands.

Use the right identifier form

Command, binding, and grant-type identifiers use lowercase hyphenated tokens, such as api-key. Error codes use lowercase underscore-separated tokens, such as not_recognized. Identity methods use an existing DID method such as did:web or a registered AEP-specific lowercase hyphenated token. Extension identifiers are absolute URIs; AEP-owned extensions should use the urn:aep:ext:<authority>:<name>#v=<version> form.

Teams defining a new method or grant type should consult the AEP specifications and registries for the authoritative registration and format requirements. An Agent integrating a Service should rely on its current Inspect advertisement, not on a registry entry alone, to decide what that Service supports.

On this page