Agent identity and assertions
Understand identity and proof
An Agent identity is an identifier whose public verification material a Service can find. It lets the Service recognize the same Agent across enrollment and later requests. In the did:web example, that identifier is a DID, and an HTTPS DID document publishes the key used for verification.
A client assertion is different: it is a short-lived token signed with the private key associated with the Agent identity for one Service and one operation. The Service verifies it to establish that the caller controls the advertised identity and intended this request. Publishing an identity does not authenticate a request, and a successful enrollment does not replace the assertion required by an authenticated AEP command.
The Agent first reads the public Inspect document without authenticating. It then uses an accepted identity method to prepare an assertion for Enroll and, when called, other authenticated AEP commands. A protected application resource accepts an AEP assertion only if the Service advertises aep-jwt for that resource.
Choose an accepted identity method
Fetch the Service's Inspect document and read identity.methods before creating an identity for that Service. Your Agent needs a method that both it and the Service support. A Service that advertises Enroll, Grant, Revoke, or Status must advertise at least one identity method and accept the baseline signed client assertion on those commands.
This guide uses did:web as a concrete example. AEP can use other registered identity methods, but each method defines its own identifier, verification-material lookup, and kid rules. If did:web is absent from the Service's list, do not use a did:web assertion against it.
Choose who holds the signing key
With self-managed signing, your Agent operator controls the key and signs its own client assertions. With delegated signing, an optional Platform provisions a Service-scoped Agent DID, publishes its verification material, and signs assertions for an authorized caller. Both paths produce an AEP assertion that the Agent presents to the Service.
A Platform is not the Service and does not receive the Agent's Enroll or Status call in place of the Service. The Service verifies the assertion under the core rules and cannot require the hosted verification endpoint. The Agent-to-Platform provisioning, signing, and lifecycle operations belong to Platform-hosted identity; they are optional for an AEP integration.
Establish a verifiable Agent identity
For a self-managed did:web identity, choose an Agent DID at an HTTPS origin you control and publish its DID document. The document must expose the public verification method that the assertion's kid selects. Keep the corresponding private signing key out of the DID document and Service requests. The Service resolves the public document to verify assertions; it does not need your private key.
Before Enroll, confirm that the DID document is reachable over HTTPS, that kid identifies a method in that document, and that its key can verify an algorithm the Service advertises in core.signing_algorithms. A missing document, missing method, incompatible key, or invalid signature causes not_recognized. The did:web identity-method draft defines resolution and key-selection rules.
Issue an assertion for each request
Use the Service DID from Inspect as aud and the Agent DID as both iss and sub. Bind op to the command being called: enroll, grant, revoke, or status. The DID portion of kid must match the Agent DID, and the signing algorithm must be one the Service advertised.
Generate current iat and exp timestamps and a fresh jti for every assertion, including one issued for a retry. The validity interval cannot exceed 300 seconds. An authenticate assertion is only for a protected resource that advertises aep-jwt; it also binds resource to that request's absolute HTTPS target. Command assertions are bound by op rather than a resource target.
Present a command assertion as Authorization: AEP <jwt>. The Service checks its signature, claims, time window, and replay identifier. The Identity methods and client assertions page gives the complete field and verification rules.
Plan for key changes and privacy
Services should cache resolved did:web documents and honor upstream HTTP cache metadata, so a changed verification method may not be visible to every Service immediately. Plan key replacement with those cache lifetimes in mind while keeping compromised keys from remaining usable longer than necessary. The identity-method draft recommends a 300-second default cache lifetime when no shorter upstream policy applies.
A DID reused across Services can correlate the Agent's activity. If your Agent operator needs those relationships kept separate, use a distinct opaque DID and signing key per Service enrollment. A Platform implementing Service-scoped hosted identities is required to provide that separation; self-managed operators can make the same choice. Avoid putting an account identifier or target Service name in a public DID path.
Check readiness before Enroll
Confirm that the Service advertises Enroll and your identity method, the Agent DID document is reachable and contains the kid verification method, and the key uses an advertised algorithm. Then prepare a fresh assertion with the Agent DID in iss and sub, the inspected Service DID in aud, and op set to enroll. If any identity or signature check cannot succeed, resolve that before sending claims or credentials.
When those checks pass, continue to Enroll an Agent for the request body and lifecycle response.
