[a]authored byinflow
Guide

Platform-hosted identity

A Platform can hold an Agent's signing key and publish its DID document. The Agent still enrolls directly with each Service, and each Service still verifies the Agent's assertions.

Know which system does what

An Agent may manage its own DID and signing key. Platform hosting is an option when the Agent or its Owner wants another system to hold the key and sign AEP client assertions. The Agent calls the Platform to obtain a Service-scoped Agent DID and assertions; it calls the Service for Inspect, Enroll, Status, Grant, Revoke, and protected resources. The Platform is not on the Service-facing command path.

Provisioning an Agent DID at the Platform does not enroll that DID with a Service. The Platform controls signing and publishes public verification material. The Service decides whether to accept enrollment and verifies each assertion under the ordinary AEP rules. A Service must not require the Platform's optional hosted-verification endpoint to accept an otherwise valid assertion.

Discover the Platform and provision a DID

The Agent reads the Platform's /.well-known/aep-platform document to find its provision and sign endpoints, supported DID methods, and signing algorithms. This discovery document is different from the Service's AEP Inspect document. The Agent then authenticates to the Platform using the Platform's own caller-authentication arrangement; the hosted-identity draft does not define that credential format.

To provision, the authenticated caller sends POST to the advertised endpoints.provision path with a nonempty Idempotency-Key and the target Service DID:

{"service_did":"did:web:api.service.example"}

The Platform returns an agent_did, a Platform-local agent_identity_id, and the URL of the published DID document. For unrelated Service DIDs, it gives the same Agent distinct, opaque public Agent DIDs unless explicit Owner policy requires reuse. That limits cross-Service correlation; the Agent must retain the mapping to the right Service DID when it later requests signing.

Ask the Platform to sign for one operation

The Agent calls the advertised sign endpoint for that agent_identity_id. The caller must be authorized by the Platform, and the POST needs a nonempty Idempotency-Key. For an Enroll assertion, the request names the target Service, uses op=enroll, and supplies a replay identifier:

{
  "jti": "01J0AEPASSERTION0000000001",
  "op": "enroll",
  "service_did": "did:web:api.service.example"
}

Signing may take time. A 202 Accepted response is from the Platform, not the Service's Enroll endpoint:

HTTP/1.1 202 Accepted

{"retry_after_seconds":"5","status":"pending"}

The Agent cannot send Enroll until signing completes. retry_after_seconds is the minimum wait before checking again, not a deadline. The Platform-hosted identity draft distinguishes the initial Sign request from a later completion request, but does not define a separate completion endpoint or a universal request body. The Agent must use the Platform's documented continuation mechanism; if none is available, it must report signing as pending rather than treating another initial request as completion.

Retrying the initial request with its original idempotency key can replay the same pending result. A completion request uses a distinct idempotency key, and retries within that completion stage reuse its key. The Node.js Agent SDK provides a pending-sign resolver for applications that integrate the Platform's continuation flow. A completed response contains the signed assertion and its expiry; the abbreviated value below is illustrative and cannot be used as a real assertion:

{
  "agent_did": "did:web:p.example:a:4Yf7p2xQd9",
  "client_assertion": "eyJhbGciOiJFUzI1NiIsImtpZCI6Ii4uLiJ9...",
  "expires_at": "2026-09-17T12:05:00Z",
  "issued_at": "2026-09-17T12:00:00Z",
  "jti": "01J0AEPASSERTION0000000001",
  "service_did": "did:web:api.service.example",
  "status": "completed"
}

The assertion is short-lived and bound to this Service DID and operation. An authenticate assertion instead needs the absolute protected-resource URI in resource; an enroll assertion must not include it. The Agent should not reuse one assertion for another operation.

Send the assertion to the Service

The Agent sends the completed assertion in Authorization: AEP <jwt> to the Service's Enroll endpoint, with the hosted agent_did in the Enroll body. The Service resolves that DID document, checks its published verification material and the assertion's signature and claims, then applies its own enrollment requirements. See Enroll an Agent for the Service request and possible enrollment states.

A Service can verify the assertion without asking the Platform to verify it. Hosted verification is optional and requires a separate trust relationship; an otherwise valid AEP assertion must not be rejected simply because the Service has no such integration.

Keep Platform and Service states separate

The Platform identity's status controls whether the Platform can sign: it will not sign for a revoked, suspended, or terminated hosted identity. The Service's enrollment status is a separate decision about that Agent DID at that Service. An active Platform identity does not mean the Service has enrolled it; an active Service enrollment does not make a blocked Platform identity able to produce a new assertion.

This guide does not define how to build a Platform or how it protects signing keys.

On this page