Protocol

Identity methods and client assertions

An Agent signs a short-lived assertion for the Service and operation it intends to use. The Service verifies the Agent identity, signature, and request binding before accepting an authenticated AEP command.

Identity and assertion serve different purposes

An Agent identity names the Agent and gives the Service a way to find its public verification material. A client assertion is a signed, short-lived token the Agent presents with a particular request. The identity can remain stable across requests; each assertion proves control of that identity for a specific Service and operation at a specific time.

An Agent reads Inspect without authentication to learn which identity methods the Service accepts. It then presents an assertion when calling an exposed Enroll, Grant, Revoke, or Status command. Enrollment records the Service's recognition of an Agent; it does not authenticate every later request on its own. Protected application resources have a separate authentication advertisement.

Use an advertised identity method

A Service lists the Agent identity methods it accepts in identity.methods in its Inspect document. A Service advertising Enroll, Grant, Revoke, or Status must accept the baseline signed client assertion for that command and advertise at least one identity method. An Agent uses a method it supports and the Service has listed; an unadvertised method fails with not_recognized.

The AEP core defines the assertion's common fields and checks, not how every identity method obtains a public key. Each concrete identity-method specification defines its identifier, Agent identifier syntax, key resolution, kid interpretation, and rotation rules. The did:web method below is one concrete choice, not the only identity method AEP can support.

Construct a client assertion

The baseline authentication for Enroll, Grant, Revoke, and Status is a signed JSON Web Token carried as Authorization: AEP <jwt>. A concrete session-credential type may also permit its credential on Status; Grant and Revoke always use the baseline assertion. Inspect is unauthenticated. The token is a compact JSON Web Signature with a JOSE header, claims set, and signature. These examples show field relationships; their timestamps and identifier are illustrative, not credentials to reuse.

{
  "alg": "EdDSA",
  "typ": "JWT",
  "kid": "did:web:agent.example.com:agents:123#key-1"
}

alg selects an algorithm advertised in core.signing_algorithms. A Service supporting the core protocol supports EdDSA and ES256; the Agent selects one the Service advertised. typ is JWT. kid identifies the Agent DID and may use a fragment to select a verification method. The none algorithm and symmetric signing algorithms are not allowed for Agent identity assertions.

{
  "iss": "did:web:agent.example.com:agents:123",
  "sub": "did:web:agent.example.com:agents:123",
  "aud": "did:web:api.example.com",
  "op": "enroll",
  "iat": 1748428800,
  "exp": 1748428860,
  "jti": "9f8a4d2e-1c3b-4f5e-8b7a-000000000000"
}

iss and sub both identify the Agent. The DID portion of kid must equal them. aud is the Service DID advertised as service.did in Inspect; it is not the Agent DID or the Service URL. op names the operation for which the assertion is presented.

Bind the assertion to one operation

For an AEP command, op is enroll, grant, revoke, or status and is valid only at the corresponding command endpoint. authenticate is not a command. It is used only for a protected resource when the Service advertises aep-jwt in authentication.methods.

An authenticate assertion also carries resource, the absolute HTTPS URI of the protected request target. The Service checks that it identifies that target. If a redirect changes the normalized resource URI, the Agent issues a new assertion for the new target. The Protected-resource authentication page covers credential carriers and redirect behavior.

Resolve a did:web Agent identity

For did:web, a Service resolves the Agent DID over HTTPS. A DID with only a host uses the host's well-known DID document; path components select a document under that path. Plaintext HTTP resolution is not allowed.

did:web:agent.example.com
  -> https://agent.example.com/.well-known/did.json
did:web:agent.example.com:agents:123
  -> https://agent.example.com/agents/123/did.json

The resolved DID document must contain the verification method selected by kid and a public key usable with alg. A missing document, missing method, incompatible key, or failed signature produces not_recognized. Services should cache resolved documents while respecting upstream cache metadata and allowing timely key replacement after compromise. The did:web identity-method draft gives the method-specific rules.

Verify the assertion

The Service parses the header, claims, and signature; rejects an algorithm it did not advertise or one AEP prohibits; resolves the identity named by kid; selects its verification method; and verifies the signature. It then checks iss, sub, aud, op, any required resource, the time window, and jti. A verification failure uses the non-disclosing not_recognized error.

iat and exp are JSON-number timestamps in seconds since the Unix epoch. They are an exception to AEP-owned protocol numbers that use JSON strings. The Service rejects an assertion if exp - iat exceeds 300 seconds and should allow no more than 30 seconds of local clock skew. The Agent generates a fresh jti for every assertion; the Service keeps a replay record keyed by at least (sub, jti) for the assertion lifetime plus accepted skew.

Next steps

For command request and lifecycle response details, continue to Enroll and Status. For practical Agent key hosting and assertion issuance, see Agent identity and assertions.