AAuth Protocol

4.1.1. Identity-Based Access

The agent signs requests with its agent token Section 5.2. The resource verifies the agent's identity via HTTP signatures and applies its own access control policy — granting or denying based on who the agent is. This replaces API keys with cryptographic identity. No authorization flow, no tokens beyond the agent token.¶

Agent                                        Resource
  |                                             |
  | HTTPSig w/ agent token                      |
  |-------------------------------------------->|
  |                                             |
  | 200 OK                                      |
  |<--------------------------------------------|

4.1.2. Resource-Managed Access (Two-Party)

The resource handles authorization itself — via interaction Section 7.2, existing OAuth/OIDC infrastructure, or internal policy. After authorization, the resource MAY return an AAuth-Access header Section 6.3 with an opaque access token for subsequent calls.¶

Agent                                        Resource
  |                                             |
  | HTTPSig w/ agent token                      |
  |-------------------------------------------->|
  |                                             |
  | 202 (interaction required)                  |
  |<--------------------------------------------|
  |                                             |
  | [user completes interaction]                |
  |                                             |
  | GET pending URL                             |
  |-------------------------------------------->|
  |                                             |
  | 200 OK                                      |
  | AAuth-Access: opaque-token                  |
  |<--------------------------------------------|
  |                                             |
  | HTTPSig w/ agent token                      |
  | Authorization: AAuth opaque-token           |
  |-------------------------------------------->|
  |                                             |
  | 200 OK                                      |
  |<--------------------------------------------|

4.1.3. PS-Managed Access (Three-Party)

The resource discovers the agent's PS from the ps claim in the agent token and issues a resource token Section 6 with aud = PS URL. The agent obtains the resource token either by calling the resource's authorization_endpoint (if published in resource metadata) or by receiving a 401 challenge with requirement=auth-token when calling the resource directly Section 6.5. The agent sends the resource token to the PS's token endpoint Section 7.1, and the PS issues an auth token Section 9.4 directly. The auth token can carry user identity, organization membership, and group information — enabling the resource to get rich authorization context from the PS without building its own identity infrastructure.¶

Agent                                 Resource       PS
  |                                      |            |
  | HTTPSig w/ agent token               |            |
  | POST authorization_endpoint          |            |
  |------------------------------------->|            |
  |                                      |            |
  | resource_token (aud = PS URL)        |            |
  |<-------------------------------------|            |
  |                                      |            |
  | HTTPSig w/ agent token               |            |
  | POST token_endpoint                  |            |
  | w/ resource_token                    |            |
  |-------------------------------------------------->|
  |                                      |            |
  | auth_token                           |            |
  |<--------------------------------------------------|
  |                                      |            |
  | HTTPSig w/ auth token                |            |
  | GET /api/documents                   |            |
  |------------------------------------->|            |
  |                                      |            |
  | 200 OK                               |            |
  |<-------------------------------------|            |

4.1.4. Federated Access (Four-Party)

The resource has its own access server. The resource issues a resource token Section 6 with aud = AS URL — either via its authorization_endpoint or a 401 challenge Section 6.5. The PS federates with the AS Section 9.3 to obtain the auth token Section 9.4.¶

Agent                                Resource   PS                    AS
  |                                     |       |                      |
  | HTTPSig w/ agent token              |       |                      |
  | POST authorization_endpoint         |       |                      |
  |------------------------------------>|       |                      |
  |                                     |       |                      |
  | resource_token (aud = AS URL)       |       |                      |
  |<------------------------------------|       |                      |
  |                                     |       |                      |
  | HTTPSig w/ agent token              |       |                      |
  | POST token_endpoint                 |       |                      |
  | w/ resource_token                   |       |                      |
  |-------------------------------------------->|                      |
  |                                     |       |                      |
  |                                     |       | HTTPSig w/ jwks_uri  |
  |                                     |       | POST token_endpoint  |
  |                                     |       | w/ resource_token    |
  |                                     |       |--------------------->|
  |                                     |       |                      |
  |                                     |       | auth_token           |
  |                                     |       |<---------------------|
  |                                     |       |                      |
  | auth_token                          |       |                      |
  |<--------------------------------------------|                      |
  |                                     |       |                      |
  | HTTPSig w/ auth token               |       |                      |
  | GET /api/documents                  |       |                      |
  |------------------------------------>|       |                      |
  |                                     |       |                      |
  | 200 OK                              |       |                      |
  |<------------------------------------|       |                      |

4.1.5. Agent Server as Resource

An agent server MAY also act as a resource — publishing metadata at /.well-known/aauth-resource.json and issuing resource tokens. This enables the agent to obtain auth tokens from its PS for the agent server's own services or infrastructure, using the standard resource token flow. How the agent obtains the resource token from the agent server is out of scope of this specification. No mission is required.¶

4.2.1. Missions

When the person's PS requires governance over the agent's actions, the agent creates a mission — a Markdown description of what it intends to accomplish. The PS and user review, clarify, and approve the mission. The approved mission is immutable — bound by its s256 hash. Missions evolve through the mission log Section 8.3: the ordered record of all agent↔PS interactions within the mission. Missions are not required for all PS interactions — an agent can get auth tokens without a mission. See Section 8 for normative requirements.¶

Agent                                     PS                        User
  |                                        |                          |
  | HTTPSig w/ agent token                 |                          |
  | POST mission_endpoint                  |                          |
  | proposal                               |                          |
  |--------------------------------------->|                          |
  |                                        |                          |
  | [clarification chat]                   | review, clarify, approve |
  |<-------------------------------------->|<------------------------>|
  |                                        |                          |
  | 200 OK                                 |                          |
  | AAuth-Mission: approver=...; s256=...  |                          |
  | {mission blob}                         |                          |
  |<---------------------------------------|                          |

Agent                                        Resource
  |                                             |
  | HTTPSig w/ agent token                      |
  | AAuth-Mission: approver=...; s256=...       |
  | POST authorization_endpoint                 |
  |-------------------------------------------->|
  |                                             |
  | resource_token                              |
  | (mission object included)                   |
  |<--------------------------------------------|

Agent                                     PS                        User
  |                                        |                          |
  | HTTPSig w/ agent token                 |                          |
  | POST interaction_endpoint              |                          |
  | type=completion, summary               |                          |
  |--------------------------------------->|                          |
  |                                        |                          |
  |                                        | present summary          |
  |                                        |------------------------->|
  |                                        |                          |
  |                                        | accept / follow-up       |
  |                                        |<-------------------------|
  |                                        |                          |
  | 200 OK (terminated)                    |                          |
  | or clarification (continues)           |                          |
  |<---------------------------------------|                          |

4.2.2. PS Governance Endpoints

The PS provides three governance endpoints. The permission Section 7.4 and interaction Section 7.6 endpoints work with or without a mission. The audit endpoint Section 7.5 requires a mission.¶

• Permission endpoint: Request permission for actions not governed by a remote resource — tool calls, file writes, sending messages.¶
• Audit endpoint: Log actions performed, providing the PS with a complete record for the mission log.¶
• Interaction endpoint: Reach the user through the PS — relay interactions, ask questions, forward payment approvals, or propose mission completion.¶

5.2.1. Agent Token Acquisition

An agent MUST obtain an agent token from its agent server before participating in the AAuth protocol. The acquisition process follows these steps:¶

1. The agent generates an ephemeral signing key pair (EdDSA is RECOMMENDED).¶
2. The agent proves its identity to the agent server through a platform-specific mechanism.¶
3. The agent server verifies the agent's identity and issues an agent token binding the agent's ephemeral public key to the agent's identifier.¶

The mechanism for proving identity is platform-dependent. See Appendix A for common patterns including server workloads (platform attestation), mobile applications (app attestation), desktop and CLI applications (user login or managed desktop attestation), and browser-based applications (WebAuthn).¶

5.2.2. Agent Token Structure

An agent token is a JWT with typ: aa-agent+jwt containing:¶

Header: - alg: Signing algorithm. EdDSA is RECOMMENDED. Implementations MUST NOT accept none. - typ: aa-agent+jwt - kid: Key identifier¶

Required payload claims: - iss: Agent server URL - dwk: aauth-agent.json — the well-known metadata document name for key discovery ([I-D.hardt-httpbis-signature-key]) - sub: Agent identifier (stable across key rotations) - jti: Unique token identifier for replay detection, audit, and revocation - cnf: Confirmation claim ([RFC7800]) with jwk containing the agent's public key - iat: Issued at timestamp - exp: Expiration timestamp. Agent tokens SHOULD NOT have a lifetime exceeding 24 hours.¶

Optional payload claims: - ps: The HTTPS URL of the agent's person server. Configured per agent instance. When present, resources can discover the agent's PS from the agent token. This claim is distinct from iss (which identifies the agent server that issued the token).¶

Agent servers MAY include additional claims in the agent token. Companion specifications may define additional claims for use by PSes or ASes in policy evaluation — for example, software attestation, platform integrity, secure enclave status, workload identity assertions, or software publisher identity. PSes and ASes MUST ignore unrecognized claims.¶

5.2.3. Agent Token Usage

Agents present agent tokens via the Signature-Key header ([I-D.hardt-httpbis-signature-key]) using scheme=jwt:¶

Signature-Key: sig=jwt;
    jwt="eyJhbGciOiJFZERTQSIsInR5cCI6Im..."

5.2.4. Agent Token Verification

Verify the agent token per [RFC7515] and [RFC7519]:¶

1. Decode the JWT header. Verify typ is aa-agent+jwt.¶
2. Verify dwk is aauth-agent.json. Discover the issuer's JWKS via {iss}/.well-known/{dwk} per the HTTP Signature Keys specification ([I-D.hardt-httpbis-signature-key]). Locate the key matching the JWT header kid and verify the JWT signature.¶
3. Verify exp is in the future and iat is not in the future.¶
4. Verify iss is a valid HTTPS URL conforming to the Server Identifier requirements.¶
5. Verify cnf.jwk matches the key used to sign the HTTP request.¶
6. If ps is present, verify it is a valid HTTPS URL conforming to the Server Identifier requirements.¶

6.2.1. Response without Resource Token

The resource handles authorization itself. It evaluates the request and returns a deferred response if user interaction is needed:¶

HTTP/1.1 202 Accepted
Location: https://resource.example/authorize/pending/abc123
Retry-After: 0
Cache-Control: no-store
AAuth-Requirement: requirement=interaction;
    url="https://resource.example/interaction"; code="A1B2-C3D4"
Content-Type: application/json

{
  "status": "pending"
}

The user completes interaction at the resource's own consent page. The agent polls the Location URL. When authorization is complete, the resource returns 200 OK and MAY include an AAuth-Access header Section 6.3 containing an opaque access token for subsequent calls.¶

HTTP/1.1 200 OK
AAuth-Access: wrapped-opaque-token-value
Content-Type: application/json

{
  "status": "authorized",
  "scope": "data.read data.write"
}

If the resource can authorize immediately (e.g., the agent's key is already authorized), it returns 200 OK directly with the optional AAuth-Access header.¶

6.2.2. Response with Resource Token

Alternatively, the resource MAY return a resource token. The resource sets the aud claim based on its configuration:¶

• If the resource has its own AS: aud = AS URL (four-party)¶
• If the resource has no AS but the agent has a PS (ps claim): aud = PS URL (three-party)¶

When the AAuth-Mission header is present, the resource includes the mission object (approver and s256) in the resource token.¶

{
  "resource_token": "eyJhbGc..."
}

The agent sends the resource token to its PS's token endpoint.¶

6.2.3. Authorization Endpoint Error Responses

Error responses use the same format as the token endpoint Section 12.5.2.¶

6.6.1. Resource Token Structure

A resource token is a JWT with typ: aa-resource+jwt containing:¶

Header: - alg: Signing algorithm. EdDSA is RECOMMENDED. Implementations MUST NOT accept none. - typ: aa-resource+jwt - kid: Key identifier¶

Payload: - iss: Resource URL - dwk: aauth-resource.json — the well-known metadata document name for key discovery ([I-D.hardt-httpbis-signature-key]) - aud: Token audience — the PS URL (when the resource delegates authorization to the agent's PS) or the AS URL (when the resource has its own access server) - jti: Unique token identifier for replay detection, audit, and revocation - agent: Agent identifier - agent_jkt: JWK Thumbprint ([RFC7638]) of the agent's current signing key - iat: Issued at timestamp - exp: Expiration timestamp - scope: Requested scopes, as a space-separated string of scope values. Companion specifications MAY define alternative authorization claims that replace scope.¶

Optional payload claims: - mission: Mission object (present when the resource is mission-aware and the agent sent an AAuth-Mission header). Contains: - approver: HTTPS URL of the entity that approved the mission - s256: SHA-256 hash of the approved mission JSON (base64url)¶

Resource tokens SHOULD NOT have a lifetime exceeding 5 minutes. The jti claim provides an audit trail for token requests; ASes are not required to enforce replay detection on resource tokens. If a resource token expires before the PS presents it to the AS (e.g., because user interaction was required), the agent MUST obtain a fresh resource token from the resource and submit a new token request to the PS. The PS SHOULD remember prior consent decisions within a mission so the user is not re-prompted when the agent resubmits a request for the same resource and scope.¶

6.6.2. Resource Token Verification

Verify the resource token per [RFC7515] and [RFC7519]:¶

1. Decode the JWT header. Verify typ is aa-resource+jwt.¶
2. Verify dwk is aauth-resource.json. Discover the issuer's JWKS via {iss}/.well-known/{dwk} per the HTTP Signature Keys specification ([I-D.hardt-httpbis-signature-key]). Locate the key matching the JWT header kid and verify the JWT signature.¶
3. Verify exp is in the future and iat is not in the future.¶
4. Verify aud matches the recipient's own identifier (the PS in three-party, or the AS in four-party).¶
5. Verify agent matches the requesting agent's identifier.¶
6. Verify agent_jkt matches the JWK Thumbprint of the key used to sign the HTTP request.¶
7. If mission is present, verify mission.approver matches the PS that sent the token request.¶

6.6.3. Resource Challenge Verification

When an agent receives a 401 response with AAuth-Requirement: requirement=auth-token:¶

1. Extract the resource-token parameter.¶
2. Decode and verify the resource token JWT.¶
3. Verify iss matches the resource the agent sent the request to.¶
4. Verify agent matches the agent's own identifier.¶
5. Verify agent_jkt matches the JWK Thumbprint of the agent's signing key.¶
6. Verify exp is in the future.¶
7. Send the resource token to the agent's PS's token endpoint.¶

7.1.1. Token Endpoint Modes

7.1.2. Concurrent Token Requests

An agent MAY have multiple token requests pending at the PS simultaneously — for example, when a mission requires access to several resources. Each request has its own pending URL and lifecycle. The PS MUST handle concurrent requests independently. Some requests may be resolved without user interaction (e.g., within existing mission scope), while others may require consent. The PS is responsible for managing concurrent user interactions — for example, by batching consent prompts or serializing them.¶

7.1.3. Agent Token Request

The agent MUST make a signed POST to the PS's token_endpoint. The request MUST include an HTTP Sig Section 12.7 and the agent MUST present its agent token via the Signature-Key header using scheme=jwt.¶

Request parameters:¶

• resource_token (REQUIRED): The resource token.¶
• upstream_token (OPTIONAL): An auth token from an upstream authorization, used in call chaining Section 10.1.¶
• justification (OPTIONAL): A Markdown string declaring why access is being requested. The PS SHOULD present this value to the user during consent. The PS MUST sanitize the Markdown before rendering to users. The PS MAY log the justification for audit and monitoring purposes. TODO: Define recommended sections.¶
• login_hint (OPTIONAL): Hint about who to authorize, per [OpenID.Core] Section 3.1.2.1.¶
• tenant (OPTIONAL): Tenant identifier, per OpenID Connect Enterprise Extensions 1.0 [OpenID.Enterprise].¶
• domain_hint (OPTIONAL): Domain hint, per OpenID Connect Enterprise Extensions 1.0 [OpenID.Enterprise].¶

Example request:¶

POST /token HTTP/1.1
Host: ps.example
Content-Type: application/json
Prefer: wait=45
Signature-Input: sig=("@method" "@authority"
    "@path" "signature-key");created=1730217600
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwt;jwt="eyJhbGc..."

{
  "resource_token": "eyJhbGc...",
  "justification": "Find available meeting times"
}

7.1.4. PS Response

When the resource token's aud matches the PS's own identifier (three-party), the PS evaluates the request and issues the auth token directly — no AS federation is needed. When aud identifies a different server (four-party), the PS federates with the AS per Section 9.3.¶

In both cases, the PS handles user consent if needed and returns one of:¶

Direct grant response (200):¶

{
  "auth_token": "eyJhbGc...",
  "expires_in": 3600
}

User interaction required response (202):¶

HTTP/1.1 202 Accepted
Location: /pending/abc123
Retry-After: 0
Cache-Control: no-store
AAuth-Requirement: requirement=interaction;
    url="https://ps.example/interaction"; code="ABCD1234"
Content-Type: application/json

{
  "status": "pending"
}

In four-party mode, the PS may also pass through a clarification from the AS to the agent via the 202 response Section 9.1.¶

7.3.1. Clarification Required

A server MUST use requirement=clarification with a 202 Accepted response when it needs the recipient to answer a question before proceeding. The response body MUST include a clarification field containing the question and MAY include timeout and options fields.¶

HTTP/1.1 202 Accepted
Location: /pending/abc123
Retry-After: 0
Cache-Control: no-store
AAuth-Requirement: requirement=clarification
Content-Type: application/json

{
  "status": "pending",
  "clarification": "Why do you need write access to my calendar?",
  "timeout": 120
}

Body fields:¶

• clarification (REQUIRED): A Markdown string containing the question.¶
• timeout (OPTIONAL): Seconds until the server times out the request. The recipient MUST respond before this deadline.¶
• options (OPTIONAL): An array of string values when the question has discrete choices.¶

The recipient MUST respond with one of the actions defined in Section 7.3.3: a clarification response, an updated request, or a cancellation. This requirement is used by both PSes (delivering user questions to agents) and ASes (requesting clarification from PSes).¶

7.3.2. Clarification Flow

When the user asks a question during consent, the PS returns a 202 with AAuth-Requirement: requirement=clarification.¶

7.3.3. Agent Response to Clarification

The agent MUST respond to a clarification with one of:¶

1. Clarification response: POST a clarification_response to the pending URL.¶
2. Updated request: POST a new resource_token to the pending URL, replacing the original request with updated scope or parameters.¶
3. Cancel request: DELETE the pending URL to withdraw the request.¶

POST /pending/abc123 HTTP/1.1
Host: ps.example
Content-Type: application/json
Signature-Input: sig=("@method" "@authority"
    "@path" "signature-key");created=1730217600
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwt;jwt="eyJhbGc..."

{
  "clarification_response":
    "I need to create a meeting invite
     for the participants you listed."
}

POST /pending/abc123 HTTP/1.1
Host: ps.example
Content-Type: application/json
Signature-Input: sig=("@method" "@authority"
    "@path" "signature-key");created=1730217600
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwt;jwt="eyJhbGc..."

{
  "resource_token": "eyJ...",
  "justification": "I've reduced my request to read-only access."
}

DELETE /pending/abc123 HTTP/1.1
Host: ps.example
Signature-Input: sig=("@method" "@authority"
    "@path" "signature-key");created=1730217600
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwt;jwt="eyJhbGc..."

7.3.4. Clarification Limits

PSes SHOULD enforce limits on clarification rounds (recommended: 5 rounds maximum). Clarification responses from agents are untrusted input and MUST be sanitized before display to the user.¶

7.4.1. Permission Request

The agent MUST make a signed POST to the PS's permission_endpoint. The request MUST include an HTTP Sig Section 12.7 and the agent MUST present its agent token via the Signature-Key header.¶

Request parameters:¶

• action (REQUIRED): A string identifying the action the agent wants to perform (e.g., a tool name).¶
• description (OPTIONAL): A Markdown string describing what the action will do and why.¶
• parameters (OPTIONAL): A JSON object containing the parameters the agent intends to pass to the action.¶
• mission (OPTIONAL): Mission object with approver and s256 fields, binding the request to a mission. When present, the PS evaluates the request against the mission context and log history.¶

POST /permission HTTP/1.1
Host: ps.example
Content-Type: application/json
Signature-Input: sig=("@method" "@authority" "@path" \
    "signature-key");created=1730217600
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwt;jwt="eyJhbGc..."

{
  "action": "SendEmail",
  "description": "Send the proposed itinerary to the user",
  "parameters": {
    "to": "user@example.com",
    "subject": "Japan trip itinerary"
  },
  "mission": {
    "approver": "https://ps.example",
    "s256": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  }
}

7.4.2. Permission Response

If the PS can decide immediately, it returns 200 OK:¶

HTTP/1.1 200 OK
Content-Type: application/json

{
  "permission": "granted"
}

The permission field is one of:¶

• granted: The agent MAY proceed with the action.¶
• denied: The agent MUST NOT proceed. The response MAY include a reason field with a Markdown string explaining why.¶

If the mission is no longer active, the PS returns a mission status error Section 8.6.¶

If the PS requires user input, it returns a deferred response Section 12.4 using the same pattern as other AAuth endpoints. The agent polls until the PS returns a final response.¶

The PS SHOULD record all permission requests and responses. When a mission is present, the PS records the permission request and response in the mission log.¶

7.5.1. Audit Request

The agent MUST make a signed POST to the PS's audit_endpoint. The request MUST include an HTTP Sig Section 12.7 and the agent MUST present its agent token via the Signature-Key header.¶

Request parameters:¶

• mission (REQUIRED): Mission object with approver and s256 fields.¶
• action (REQUIRED): A string identifying the action that was performed.¶
• description (OPTIONAL): A Markdown string describing what was done and the outcome.¶
• parameters (OPTIONAL): A JSON object containing the parameters that were used.¶
• result (OPTIONAL): A JSON object containing the result or outcome of the action.¶

POST /audit HTTP/1.1
Host: ps.example
Content-Type: application/json
Signature-Input: sig=("@method" "@authority" "@path" \
    "signature-key");created=1730217600
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwt;jwt="eyJhbGc..."

{
  "mission": {
    "approver": "https://ps.example",
    "s256": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  },
  "action": "WebSearch",
  "description": "Searched for flights to Tokyo in May",
  "parameters": {
    "query": "flights to Tokyo May 2026"
  },
  "result": {
    "status": "completed",
    "summary": "Found 12 flight options"
  }
}

7.5.2. Audit Response

The PS returns 201 Created to acknowledge the record:¶

HTTP/1.1 201 Created

The audit endpoint is fire-and-forget — the agent SHOULD NOT block on the response. The PS records the audit entry in the mission log. The PS MAY use audit records to detect anomalous behavior, alert the user, or revoke the mission.¶

If the mission is no longer active, the PS returns a mission status error Section 8.6.¶

7.6.1. Interaction Request

The agent MUST make a signed POST to the PS's interaction_endpoint. The request MUST include an HTTP Sig Section 12.7 and the agent MUST present its agent token via the Signature-Key header.¶

Request parameters:¶

• type (REQUIRED): The type of interaction. One of interaction, payment, question, or completion.¶
• description (OPTIONAL): A Markdown string providing context for the user.¶
• url (OPTIONAL): The interaction URL to relay to the user (for interaction and payment types).¶
• code (OPTIONAL): The interaction code associated with the URL.¶
• question (OPTIONAL): A Markdown string containing a question for the user (for question type).¶
• summary (OPTIONAL): A Markdown string summarizing what the agent accomplished (for completion type).¶
• mission (OPTIONAL): Mission object with approver and s256 fields, binding the request to a mission.¶

Relay interaction example:¶

POST /interaction HTTP/1.1
Host: ps.example
Content-Type: application/json
Signature-Input: sig=("@method" "@authority" "@path" \
    "signature-key");created=1730217600
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwt;jwt="eyJhbGc..."

{
  "type": "interaction",
  "description": "The booking service needs you to confirm payment",
  "url": "https://booking.example/confirm",
  "code": "X7K2-M9P4",
  "mission": {
    "approver": "https://ps.example",
    "s256": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  }
}

Completion example:¶

POST /interaction HTTP/1.1
Host: ps.example
Content-Type: application/json
Signature-Input: sig=("@method" "@authority" "@path" \
    "signature-key");created=1730217600
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwt;jwt="eyJhbGc..."

{
  "type": "completion",
  "summary": "# Japan Trip Booked\n\n
    Booked round-trip flights on ANA and
    10 nights across three cities.
    Total cost: $4,850.
    Itinerary sent to your email.",
  "mission": {
    "approver": "https://ps.example",
    "s256": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  }
}

7.6.2. Interaction Response

For interaction and payment types, the PS relays the interaction to the user and returns a deferred response Section 12.4. The agent polls until the user completes the interaction.¶

For question type, the PS delivers the question to the user and returns the answer:¶

HTTP/1.1 200 OK
Content-Type: application/json

{
  "answer": "Yes, go ahead with the refundable option."
}

For completion type, the PS presents the summary to the user. The user either accepts — the PS terminates the mission and returns 200 OK — or responds with follow-up questions via clarification Section 7.3, keeping the mission active. The PS returns a deferred response while the user reviews.¶

If the PS cannot reach the user and the agent does not have the interaction capability, the PS returns interaction_required. If the mission is no longer active, the PS returns a mission status error Section 8.6. The PS SHOULD record all interaction requests and responses. When a mission is active, the PS records the interaction in the mission log.¶

9.1.1. PS-to-AS Token Request

The PS MUST make a signed POST to the AS's token_endpoint. The PS authenticates via an HTTP Sig Section 12.7.¶

Request parameters:¶

• resource_token (REQUIRED): The resource token issued by the resource.¶
• agent_token (REQUIRED): The agent's agent token.¶
• upstream_token (OPTIONAL): An auth token from an upstream authorization, used in call chaining Section 10.1.¶

Example request:¶

POST /token HTTP/1.1
Host: as.resource.example
Content-Type: application/json
Signature-Input: sig=("@method" "@authority"
    "@path" "signature-key");created=1730217600
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwks_uri;
    jwks_uri="https://ps.example/.well-known/jwks.json"

{
  "resource_token": "eyJhbGc...",
  "agent_token": "eyJhbGc..."
}

9.1.2. AS Response

The PS calls the AS token endpoint and follows the standard deferred response loop Section 12.4: it handles 202 and 402 responses and continues until it receives a 200 with an auth token or a terminal error.¶

Direct grant response (200):¶

{
  "auth_token": "eyJhbGc...",
  "expires_in": 3600
}

The AS MAY return 202 Accepted with an AAuth-Requirement header indicating what is needed before it can issue an auth token:¶

• requirement=claims Section 9.2: The AS needs identity claims. The body includes required_claims. The PS MUST provide the requested claims (including a directed sub identifier for the resource) by POSTing to the Location URL. The AS cannot know what claims it needs until it has processed the resource token.¶
• requirement=clarification Section 7.3.1: The AS needs a question answered. The PS triages who answers: itself (if mission context has the answer), the user, or the agent. The PS MAY pass the clarification down to the agent via a 202 response.¶
• requirement=interaction Section 12.3: The AS requires user interaction — for example, the user must authenticate at the AS to bind their PS, or the resource owner must approve access. The PS directs the user to the AS's interaction URL, or passes the interaction requirement back to the agent.¶
• requirement=approval Section 12.3: The AS is obtaining approval without requiring user direction.¶

Payment required (402):¶

The AS MAY return 402 Payment Required when a billing relationship is required before it will issue auth tokens. The 402 response includes payment details per an applicable payment protocol such as x402 [x402] or the Machine Payment Protocol (MPP) ([I-D.ryan-httpauth-payment]). The response MUST include a Location header for the PS to poll after payment is settled.¶

HTTP/1.1 402 Payment Required
Location: https://as.resource.example/token/pending/xyz
WWW-Authenticate: Payment id="x7Tg2pLq", method="stripe",
    request="eyJhbW91bnQiOiIxMDAw..."

The PS settles payment per the indicated protocol and polls the Location URL. When payment is confirmed, the AS continues processing the token request — which may result in a 200 with an auth token, or a further 202 requiring claims, interaction, or approval.¶

The PS caches the billing relationship per AS. Future token requests from the same PS to the same AS skip the billing step. The payment protocol, settlement mechanism, and billing terms are out of scope for this specification.¶

9.1.3. Auth Token Delivery

When the AS issues an auth token (200 response), the PS MUST verify the auth token before returning it to the agent:¶

1. Verify the auth token JWT signature using the AS's JWKS Section 12.8.¶
2. Verify iss matches the AS the PS sent the token request to.¶
3. Verify aud matches the resource identified by the resource token's iss.¶
4. Verify agent matches the agent that submitted the token request.¶
5. Verify cnf.jwk matches the agent's signing key.¶
6. Verify act is present and accurately reflects the delegation chain — act.sub identifies the requesting agent, and any nested act claims match the upstream delegation context.¶
7. Verify scope is consistent with what was requested — not broader than the scope in the resource token.¶

After verification, the PS returns the auth token to the agent. The agent presents the auth token to the resource via the Signature-Key header Section 9.4.2. The resource verifies the auth token against the AS's JWKS Section 9.4.3.¶

The agent receives the auth token from its trusted PS, so signature verification is not strictly required. However, agents SHOULD verify the auth token's signature to detect errors early. Agents MUST verify that aud, cnf, agent, and act match their own values.¶

9.3.1. PS-AS Trust Establishment

Trust between the PS and AS is not a separate registration step — it emerges from the AS's response to the PS's first token request. The AS evaluates the token request and responds based on its current policy:¶

• Pre-established: A business relationship configured between the PS and AS, potentially including payment terms, SLA, and compliance requirements. The AS recognizes the PS and processes the token request directly.¶
• Interaction: The AS returns 202 with requirement=interaction, directing the user to authenticate at the AS and confirm their PS. After this one-time binding, the AS trusts future requests from that PS for that user. This is the primary mechanism for establishing trust dynamically.¶
• Payment: The AS returns 402, requiring the PS to establish a billing relationship before tokens will be issued. The PS settles payment per the indicated protocol and polls for completion. After billing is established, the AS trusts future requests from that PS.¶
• Claims only: The AS may trust any PS that can provide sufficient identity claims for a policy decision, without requiring a prior relationship.¶

These mechanisms may compose: for example, the AS may first require payment (402), then interaction for user binding (202), then claims (202) before issuing an auth token. Each step uses the same Location URL for polling.¶

PS                        User                    AS
  |                         |                       |
  |  POST /token            |                       |
  |  resource_token,        |                       |
  |  agent_token            |                       |
  |------------------------------------------------>|
  |                         |                       |
  |  402 Payment Required   |                       |
  |  Location: /token/pending/xyz                   |
  |<------------------------------------------------|
  |                         |                       |
  |  [PS settles payment per indicated protocol]    |
  |                         |                       |
  |  GET /token/pending/xyz |                       |
  |------------------------------------------------>|
  |                         |                       |
  |  202 Accepted           |                       |
  |  requirement=interaction|                       |
  |  url=".../authorize/abc"|                       |
  |<------------------------------------------------|
  |                         |                       |
  |  direct user to URL     |                       |
  |------------------------>|                       |
  |                         |  authenticate, bind PS|
  |                         |---------------------->|
  |                         |                       |
  |  GET /token/pending/xyz |                       |
  |------------------------------------------------>|
  |                         |                       |
  |  202 Accepted           |                       |
  |  requirement=claims     |                       |
  |<------------------------------------------------|
  |                         |                       |
  |  POST /token/pending/xyz|                       |
  |  {sub, email, org}      |                       |
  |------------------------------------------------>|
  |                         |                       |
  |  200 OK (auth_token)    |                       |
  |<------------------------------------------------|
  |                         |                       |

{: #fig-mm-as-trust title="PS-AS Trust Establishment (all steps shown — most requests skip some)"}¶

9.3.2. AS Decision Logic (Non-Normative)

The following is a non-normative description of how an AS might evaluate a token request:¶

1. PS = AS (same entity): Grant directly. When an organization controls both the PS and AS, the federation call is internal and trust is implicit.¶
2. User has bound this PS at the AS: Apply the user's configured policy for this PS.¶
3. PS is pre-established (enterprise agreement): Apply the organization's configured policy.¶
4. Resource is open or has a free tier: Grant with restricted scope or rate limits.¶
5. Resource requires billing: Return 402 with payment details.¶
6. Resource requires user binding: Return 202 with requirement=interaction.¶
7. AS needs identity claims to decide: Return 202 with requirement=claims.¶
8. Insufficient trust for requested scope: Return 403.¶

The AS is not required to follow this order. The decision logic is entirely at the AS's discretion based on resource policy.¶

9.3.3. Organization Visibility

Organizations benefit from the trust model: an organization's agents share a single PS, and internal resources may share a single AS. The PS provides centralized audit across all agents and missions. Federation is only incurred at the boundary, when an internal agent accesses an external resource. When an organization controls both the PS and AS, the federation call is internal and trust is implicit — this is the degenerate case of the four-party model collapsing to fewer parties.¶

9.4.1. Auth Token Structure

An auth token is a JWT with typ: aa-auth+jwt containing:¶

Header: - alg: Signing algorithm. EdDSA is RECOMMENDED. Implementations MUST NOT accept none. - typ: aa-auth+jwt - kid: Key identifier¶

Required payload claims: - iss: The URL of the server that issued the auth token — an AS (four-party) or a PS (three-party) - dwk: The well-known metadata document name for key discovery ([I-D.hardt-httpbis-signature-key]). aauth-access.json when issued by an AS, aauth-person.json when issued by a PS. - aud: The URL of the resource the agent is authorized to access. - jti: Unique token identifier for replay detection, audit, and revocation - agent: Agent identifier - cnf: Confirmation claim with jwk containing the agent's public key - act: Actor claim ([RFC8693], Section 4.1) identifying the entity that requested this auth token. In direct authorization, act.sub is the agent identifier. In call chaining, act nests to record the full delegation chain — each intermediary's identity is preserved as a nested act claim within the outer act. This enables resources to see the complete chain of delegation and make authorization decisions accordingly. - iat: Issued at timestamp - exp: Expiration timestamp. Auth tokens MUST NOT have a lifetime exceeding 1 hour.¶

Conditional payload claims (at least one MUST be present): - sub: Directed user identifier. An opaque string that identifies the user. The PS SHOULD provide a pairwise pseudonymous identifier per resource (aud), preserving user privacy — different resources see different sub values for the same user. - scope: Authorized scopes, as a space-separated string of scope values consistent with [RFC9068] Section 2.2.3¶

At least one of sub or scope MUST be present.¶

Optional payload claims: - mission: Mission object. Present when the auth token was issued in the context of a mission. Contains: - approver: HTTPS URL of the entity that approved the mission - s256: SHA-256 hash of the approved mission JSON (base64url)¶

The auth token MAY include additional claims registered in the IANA JSON Web Token Claims Registry [RFC7519] or defined in OpenID Connect Core 1.0 [OpenID.Core] Section 5.1.¶

9.4.2. Auth Token Usage

Agents present auth tokens via the Signature-Key header ([I-D.hardt-httpbis-signature-key]) using scheme=jwt:¶

Signature-Key: sig=jwt;
    jwt="eyJhbGciOiJFZERTQSIsInR5cCI6ImF1dGgr..."

9.4.3. Auth Token Verification

When a resource receives an auth token, verify per [RFC7515] and [RFC7519]:¶

1. Decode the JWT header. Verify typ is aa-auth+jwt.¶
2. Verify dwk is aauth-access.json (AS-issued) or aauth-person.json (PS-issued). Discover the issuer's JWKS via {iss}/.well-known/{dwk} per the HTTP Signature Keys specification ([I-D.hardt-httpbis-signature-key]). Locate the key matching the JWT header kid and verify the JWT signature.¶
3. Verify exp is in the future and iat is not in the future.¶
4. Verify iss is a valid HTTPS URL.¶
5. Verify aud matches the resource's own identifier.¶
6. Verify agent matches the agent identifier from the request's signing context.¶
7. Verify cnf.jwk matches the key used to sign the HTTP request.¶
8. Verify act is present and act.sub matches the agent identifier from the request's signing context.¶
9. Verify that at least one of sub or scope is present.¶

9.4.4. Auth Token Response Verification

When an agent receives an auth token:¶

1. SHOULD verify the auth token JWT signature using the issuer's JWKS (the AS in four-party, or the PS in three-party). The agent trusts its PS, so signature verification is not required but is RECOMMENDED to detect errors early.¶
2. Verify iss matches the resource token's aud claim.¶
3. Verify aud matches the resource the agent intends to access.¶
4. Verify cnf.jwk matches the agent's own signing key.¶
5. Verify agent matches the agent's own identifier.¶
6. Verify act.sub matches the agent's own identifier.¶

9.4.5. Upstream Token Verification

When the PS receives an upstream_token parameter in a call chaining request:¶

1. Perform Auth Token Verification Section 9.4.3 on the upstream token.¶
2. Verify iss is a trusted AS (an AS whose auth token the PS previously brokered).¶
3. Verify the aud in the upstream token matches the resource that is now acting as an agent (i.e., the upstream token was issued for the intermediary resource).¶
4. The PS constructs the act claim for the downstream auth token by nesting the upstream token's act claim inside a new act object identifying the intermediary resource's agent identity. This preserves the complete delegation chain.¶
5. The PS evaluates its own policy based on the upstream token's claims and mission context. The resulting downstream authorization is not required to be a subset of the upstream scopes — see Section 10.1.¶

12.3.1. AAuth-Requirement Header Structure

The AAuth-Requirement header field is a Dictionary ([RFC8941], Section 3.2). It MUST contain the following member:¶

• requirement: A Token ([RFC8941], Section 3.3.4) indicating the requirement type.¶

Additional members are defined per requirement value. Recipients MUST ignore unknown members.¶

Example:¶

AAuth-Requirement: requirement=auth-token; resource-token="eyJ..."

12.3.2. Requirement Values

The requirement value is an extension point. This document defines the following values:¶

The auth-token requirement is defined in Section 6.5; the interaction and approval requirements are defined in this section; clarification in Section 7.3.1; and claims in Section 9.2.¶

12.3.3. Interaction Required

When a server requires user action — such as authentication, consent, payment approval, or any decision requiring a human in the loop — it returns a 202 Accepted response:¶

HTTP/1.1 202 Accepted
AAuth-Requirement:
    requirement=interaction;
    url="https://example.com/interact";
    code="A1B2-C3D4"
Location: /pending/f7a3b9c
Retry-After: 0

The AAuth-Requirement header MUST include the following parameters:¶

• url (String): The interaction URL where the user completes the required action. MUST use the https scheme and MUST NOT contain query or fragment components.¶
• code (String): An interaction code that links the agent's pending request to the user's session at the interaction URL.¶

The response MUST also include:¶

• Location: A URL the agent polls (with GET) for a terminal response.¶
• Retry-After: Recommended polling interval in seconds.¶

The agent constructs a user-facing URL by appending the code as a query parameter: {url}?code={code}. The agent then directs the user to this URL using one of:¶

• Browser redirect: The agent opens the URL in the user's browser.¶
• Display code: The agent displays the url and code for the user to enter manually. The agent MAY also render the constructed URL as a QR code for the user to scan with their phone.¶

After directing the user, the agent polls the Location URL with GET requests, respecting the Retry-After interval. A 202 response means the request is still pending. A non-202 response is terminal — 200 indicates success, 403 indicates denial, and 408 indicates timeout.¶

Agent                        User                         Server
  |                            |                             |
  |  202 Accepted                                            |
  |  AAuth-Requirement:                                      |
  |    requirement=interaction;                              |
  |    url="..."; code="..."                                 |
  |  Location: /pending/...                                  |
  |<---------------------------------------------------------|
  |                            |                             |
  |  open {url}?code={code}    |                             |
  |  (or display code / QR)    |                             |
  |--------------------------->|                             |
  |                            |                             |
  |                            |  {url}?code={code}          |
  |                            |---------------------------->|
  |                            |                             |
  |                            |  user completes action      |
  |                            |<----------------------------|
  |                            |                             |
  |  GET /pending/...                                        |
  |--------------------------------------------------------->|
  |                            |                             |
  |  200 OK                                                  |
  |<---------------------------------------------------------|

Use cases: User login, consent, payment confirmation, document review, CAPTCHA, any workflow requiring human action.¶

12.3.4. Approval Pending

When a server is obtaining approval from another party without requiring the agent to direct a user — for example, via push notification, email, or administrator review:¶

HTTP/1.1 202 Accepted
AAuth-Requirement: requirement=approval
Location: /pending/f7a3b9c
Retry-After: 30

The response MUST include Location and Retry-After. The agent polls the Location URL with GET requests until a terminal response is received. No user action is required at the agent side. The same terminal response codes apply as for interaction.¶

Use cases: Administrator approval, resource owner consent, compliance review, direct user authorization via established communication channel.¶

12.4.1. Initial Request

The agent makes a request and signals its willingness to wait using the Prefer header ([RFC7240]):¶

POST /token HTTP/1.1
Host: auth.example
Content-Type: application/json
Prefer: wait=45
Signature-Input: sig=("@method" "@authority"
    "@path" "signature-key");created=1730217600
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwt;jwt="eyJhbGc..."

{
  "resource_token": "eyJhbGc..."
}

12.4.2. Pending Response

When the server cannot resolve the request within the wait period:¶

HTTP/1.1 202 Accepted
Location: /pending/f7a3b9c
Retry-After: 0
Cache-Control: no-store
Content-Type: application/json

{
  "status": "pending"
}

Headers:¶

• Location (REQUIRED): The pending URL. The Location URL MUST be on the same origin as the responding server.¶
• Retry-After (REQUIRED): Seconds the agent SHOULD wait before polling. 0 means retry immediately.¶
• Cache-Control: no-store (REQUIRED): Prevents caching of pending responses.¶
• AAuth-Requirement (OPTIONAL): Present when user interaction or approval is required. The url and code parameters are defined in Section 12.3.¶

Body fields:¶

• status (REQUIRED): "pending" while the request is waiting. "interacting" when the user has arrived at the interaction endpoint. Agents MUST treat unrecognized status values as "pending" and continue polling.¶

Additional body fields may be present depending on the AAuth-Requirement value — for example, clarification and timeout with requirement=clarification, or required_claims with requirement=claims. See the specific requirement definitions for details.¶

12.4.3. Polling with GET

After receiving a 202, the agent switches to GET for all subsequent requests to the Location URL. The agent does NOT resend the original request body. Exception: During clarification chat, the agent uses POST to deliver a clarification response.¶

The agent MUST respect Retry-After values. If a Retry-After header is not present, the default polling interval is 5 seconds. If the server responds with 429 Too Many Requests, the agent MUST increase its polling interval by 5 seconds (linear backoff, following the pattern in [RFC8628], Section 3.5). The Prefer: wait=N header ([RFC7240]) MAY be included on polling requests to signal the agent's willingness to wait for a long-poll response.¶

12.4.4. Deferred Response State Machine

The following state machine applies to any AAuth endpoint that returns a 202 Accepted response — including PS token endpoints, AS token endpoints, and resource endpoints during call chaining. A non-202 response terminates polling.¶

Initial request (with Prefer: wait=N)
    |
    +-- 200 --> done — process response body
    +-- 202 --> note Location URL, check requirement/code
    +-- 400 --> invalid request — check error field, fix and retry
    +-- 401 --> invalid signature — check credentials;
    |           obtain auth token if resource challenge
    +-- 402 --> payment required (settle payment, poll Location)
    +-- 500 --> server error — start over
    +-- 503 --> back off per Retry-After, retry
               |
               GET Location (with Prefer: wait=N)
               |
               +-- 200 --> done — process response body
               +-- 202 --> continue polling (check status/clarification)
               |           status=interacting → stop prompting user
               +-- 403 --> denied or abandoned — surface to user
               +-- 408 --> expired — MAY initiate a fresh request
               +-- 410 --> gone — MUST NOT retry
               +-- 429 --> slow down — increase interval by 5s
               +-- 500 --> server error — start over
               +-- 503 --> temporarily unavailable
                           back off per Retry-After

12.5.1. Authentication Errors

A 401 response from any AAuth endpoint uses the Signature-Error header as defined in ([I-D.hardt-httpbis-signature-key]).¶

12.5.2. Token Endpoint Error Response Format

Token endpoint errors use Content-Type: application/json ([RFC8259]) with the following members:¶

• error (REQUIRED): String. A single error code.¶
• error_description (OPTIONAL): String. A human-readable description.¶

12.5.3. Token Endpoint Error Codes

12.5.4. Polling Error Codes

12.7.1. Signature Algorithms

Agents and resources MUST support EdDSA using Ed25519 ([RFC8032]). Agents and resources SHOULD support ECDSA using P-256 with deterministic signatures ([RFC6979]). The alg parameter in the JWK ([RFC7517]) key representation identifies the algorithm. See the IANA JSON Web Signature and Encryption Algorithms registry ([RFC7518], Section 7.1) for the full list of algorithm identifiers.¶

12.7.2. Keying Material

The signing key is conveyed in the Signature-Key header ([I-D.hardt-httpbis-signature-key]). The Signature-Key scheme determines how the server obtains the public key:¶

• For pseudonym: the agent uses scheme=hwk (inline public key) or scheme=jkt-jwt (delegation from a hardware-backed key).¶
• For identity: the agent uses scheme=jwks_uri (JWKS endpoint) or scheme=jwt (JWT with public key in cnf claim).¶

See the Signature-Key specification ([I-D.hardt-httpbis-signature-key]) for scheme definitions, key discovery, and verification procedures.¶

12.7.3. Signing (Agent)

The agent creates an HTTP Message Signature ([RFC9421]) on each request, including the following headers:¶

• Signature-Key: Public key or key reference for signature verification¶
• Signature-Input: Signature metadata including covered components¶
• Signature: The HTTP message signature¶

12.7.4. Verification (Server)

When a server receives a signed request, it MUST perform the following steps. Any failure MUST result in a 401 response with the appropriate Signature-Error header ([I-D.hardt-httpbis-signature-key]).¶

1. Extract the Signature, Signature-Input, and Signature-Key headers. If any are missing, return invalid_request.¶
2. Verify that the Signature-Input covers the required components defined in Section 12.7.3.1. If the server requires additional components, verify those are covered as well. If not, return invalid_input with required_input.¶
3. Verify the created parameter is present and within the server's signature validity window of the server's current time. The default window is 60 seconds. Servers MAY advertise a different window via their metadata (e.g., signature_window in resource metadata). Reject with invalid_signature if outside this window. Servers and agents SHOULD synchronize their clocks using NTP ([RFC5905]).¶
4. Determine the signature algorithm from the alg parameter in the key. If the algorithm is not supported, return unsupported_algorithm.¶
5. Obtain the public key from the Signature-Key header according to the scheme, as specified in ([I-D.hardt-httpbis-signature-key]). Return invalid_key if the key cannot be parsed, unknown_key if the key is not found at the jwks_uri, invalid_jwt if a JWT scheme fails verification, or expired_jwt if the JWT has expired.¶
6. Verify the HTTP Message Signature ([RFC9421]) using the obtained public key and determined algorithm. Return invalid_signature if verification fails.¶

12.9.1. Server Identifiers

The issuer values in metadata documents that identify agent servers, resources, access servers, and person servers MUST conform to the following:¶

• MUST use the https scheme¶
• MUST contain only scheme and host (no port, path, query, or fragment)¶
• MUST NOT include a trailing slash¶
• MUST be lowercase¶
• Internationalized domain names MUST use the ASCII-Compatible Encoding (ACE) form (A-labels) as defined in [RFC5890]¶

Valid identifiers:¶

• https://agent.example¶
• https://xn--nxasmq6b.example (internationalized domain in ACE form)¶

Invalid identifiers:¶

• http://agent.example (not HTTPS)¶
• https://Agent.Example (not lowercase)¶
• https://agent.example:8443 (contains port)¶
• https://agent.example/v1 (contains path)¶
• https://agent.example/ (trailing slash)¶

Implementations MUST perform exact string comparison on server identifiers.¶

12.9.2. Endpoint URLs

The token_endpoint, authorization_endpoint, mission_endpoint, and callback_endpoint values MUST conform to the following:¶

• MUST use the https scheme¶
• MUST NOT contain a fragment¶
• MUST NOT contain a query string¶

When localhost_callback_allowed is true in the agent's metadata, the agent MAY use a localhost callback URL as the callback parameter to the interaction endpoint.¶

12.9.3. Other URLs

The jwks_uri, tos_uri, policy_uri, logo_uri, and logo_dark_uri values MUST use the https scheme.¶

12.10.1. Agent Server Metadata

Published at /.well-known/aauth-agent.json:¶

{
  "issuer": "https://agent.example",
  "jwks_uri": "https://agent.example/.well-known/jwks.json",
  "client_name": "Example AI Assistant",
  "logo_uri": "https://agent.example/logo.png",
  "logo_dark_uri": "https://agent.example/logo-dark.png",
  "callback_endpoint": "https://agent.example/callback",
  "localhost_callback_allowed": true,
  "tos_uri": "https://agent.example/tos",
  "policy_uri": "https://agent.example/privacy"
}

Fields:¶

• issuer (REQUIRED): The agent server's HTTPS URL (the domain in agent identifiers it issues). This is the value placed in the iss claim of agent tokens.¶
• jwks_uri (REQUIRED): URL to the agent server's JSON Web Key Set¶
• client_name (OPTIONAL): Human-readable agent name (per [RFC7591])¶
• logo_uri (OPTIONAL): URL to agent logo (per [RFC7591])¶
• logo_dark_uri (OPTIONAL): URL to agent logo for dark backgrounds¶
• callback_endpoint (OPTIONAL): The agent's HTTPS callback endpoint URL¶
• login_endpoint (OPTIONAL): URL where third parties can direct users to initiate authentication Section 11¶
• localhost_callback_allowed (OPTIONAL): Boolean. Default: false.¶
• tos_uri (OPTIONAL): URL to terms of service (per [RFC7591])¶
• policy_uri (OPTIONAL): URL to privacy policy (per [RFC7591])¶

12.10.2. Person Server Metadata

Published at /.well-known/aauth-person.json:¶

{
  "issuer": "https://ps.example",
  "token_endpoint": "https://ps.example/token",
  "mission_endpoint": "https://ps.example/mission",
  "permission_endpoint": "https://ps.example/permission",
  "audit_endpoint": "https://ps.example/audit",
  "interaction_endpoint": "https://ps.example/interaction",
  "mission_control_endpoint": "https://ps.example/mission-control",
  "jwks_uri": "https://ps.example/.well-known/jwks.json"
}

Fields:¶

• issuer (REQUIRED): The PS's HTTPS URL. MUST match the URL used to fetch the metadata document. This is the value placed in the iss claim of JWTs issued by the PS.¶
• token_endpoint (REQUIRED): URL where agents send token requests¶
• mission_endpoint (OPTIONAL): URL for mission lifecycle operations (proposal, status). Present when the PS supports missions.¶
• permission_endpoint (OPTIONAL): URL where agents request permission for actions not governed by a remote resource Section 7.4¶
• audit_endpoint (OPTIONAL): URL where agents log actions performed Section 7.5¶
• interaction_endpoint (OPTIONAL): URL where agents relay interactions to the user through the PS Section 7.6¶
• mission_control_endpoint (OPTIONAL): URL for mission administrative interface¶
• revocation_endpoint (OPTIONAL): URL where authorized parties can revoke tokens Section 12.6¶
• jwks_uri (REQUIRED): URL to the PS's JSON Web Key Set¶
• scopes_supported (RECOMMENDED): Array of scope values the PS supports, including identity scopes (e.g., openid, profile, email) and enterprise scopes (e.g., org, groups, roles)¶
• claims_supported (RECOMMENDED): Array of identity claim names the PS can provide (e.g., sub, email, name, org)¶

12.10.3. Access Server Metadata

Published at /.well-known/aauth-access.json:¶

{
  "issuer": "https://as.resource.example",
  "token_endpoint": "https://as.resource.example/token",
  "jwks_uri": "https://as.resource.example/.well-known/jwks.json"
}

Fields:¶

• issuer (REQUIRED): The AS's HTTPS URL. MUST match the URL used to fetch the metadata document. This is the value placed in the iss claim of auth tokens.¶
• token_endpoint (REQUIRED): URL where PSes send token requests¶
• revocation_endpoint (OPTIONAL): URL where authorized parties can revoke tokens Section 12.6¶
• jwks_uri (REQUIRED): URL to the AS's JSON Web Key Set¶

12.10.4. Resource Metadata

Published at /.well-known/aauth-resource.json:¶

{
  "issuer": "https://resource.example",
  "jwks_uri": "https://resource.example/.well-known/jwks.json",
  "client_name": "Example Data Service",
  "logo_uri": "https://resource.example/logo.png",
  "logo_dark_uri": "https://resource.example/logo-dark.png",
  "authorization_endpoint": "https://resource.example/authorize",
  "scope_descriptions": {
    "data.read": "Read access to your data and documents",
    "data.write": "Create and update your data and documents",
    "data.delete": "Permanently delete your data and documents"
  },
  "additional_signature_components": ["content-type", "content-digest"]
}

Fields:¶

• issuer (REQUIRED): The resource's HTTPS URL. This is the value placed in the iss claim of resource tokens.¶
• jwks_uri (REQUIRED): URL to the resource's JSON Web Key Set¶
• client_name (OPTIONAL): Human-readable resource name (per [RFC7591])¶
• logo_uri (OPTIONAL): URL to resource logo (per [RFC7591])¶
• logo_dark_uri (OPTIONAL): URL to resource logo for dark backgrounds¶
• authorization_endpoint (OPTIONAL): URL where agents request authorization Section 6.1. When absent, the resource issues resource tokens and interaction requirements via 401 responses (#requirement-auth-token, #resource-managed-auth).¶
• login_endpoint (OPTIONAL): URL where third parties can direct users to initiate authentication Section 11¶
• scope_descriptions (OPTIONAL): Object mapping scope values to Markdown strings for consent display. Scope values are resource-specific; resources that already define OAuth scopes SHOULD use the same scope values in AAuth. Identity-related scopes (e.g., openid, profile, email) follow [OpenID.Core].¶
• signature_window (OPTIONAL): Integer. The signature validity window in seconds for the created timestamp. Default: 60. Resources serving agents with poor clock synchronization (mobile, IoT) MAY advertise a larger value. High-security resources MAY advertise a smaller value.¶
• additional_signature_components (OPTIONAL): Array of HTTP message component identifiers ([RFC9421]) that agents MUST include in the Signature-Input covered components when signing requests to this resource, in addition to the base components required by the HTTP Message Signatures profile ([I-D.hardt-httpbis-signature-key])¶
• revocation_endpoint (OPTIONAL): URL where authorized parties can revoke auth tokens for this resource Section 12.6¶

16.4.1. application/aa-agent+jwt

• Type name: application¶
• Subtype name: aa-agent+jwt¶
• Required parameters: N/A¶
• Optional parameters: N/A¶
• Encoding considerations: binary; a JWT is a sequence of Base64url-encoded parts separated by period characters¶
• Security considerations: See Section 14¶
• Interoperability considerations: N/A¶
• Published specification: This document, Section 5.2¶
• Applications that use this media type: AAuth agents, PSes, and ASes¶
• Fragment identifier considerations: N/A¶

16.4.2. application/aa-auth+jwt

• Type name: application¶
• Subtype name: aa-auth+jwt¶
• Required parameters: N/A¶
• Optional parameters: N/A¶
• Encoding considerations: binary; a JWT is a sequence of Base64url-encoded parts separated by period characters¶
• Security considerations: See Section 14¶
• Interoperability considerations: N/A¶
• Published specification: This document, Section 9.4¶
• Applications that use this media type: AAuth ASes, agents, and resources¶
• Fragment identifier considerations: N/A¶

16.4.3. application/aa-resource+jwt

• Type name: application¶
• Subtype name: aa-resource+jwt¶
• Required parameters: N/A¶
• Optional parameters: N/A¶
• Encoding considerations: binary; a JWT is a sequence of Base64url-encoded parts separated by period characters¶
• Security considerations: See Section 14¶
• Interoperability considerations: N/A¶
• Published specification: This document, Section 6¶
• Applications that use this media type: AAuth resources and ASes¶
• Fragment identifier considerations: N/A¶

C.1.1. Why HTTPS-Based Agent Identity

HTTPS URLs as agent identifiers enable dynamic ecosystems without pre-registration.¶

C.1.2. Why Per-Instance Agent Identity

OAuth's client_id identifies an application — every instance of the same app shares a single identifier and typically a single set of credentials. AAuth's aauth:local@domain agent identifier identifies a specific instance with its own signing key. This enables per-instance authorization (grant access to this specific agent process, not all instances of the app), per-instance revocation (revoke one compromised instance without affecting others), and per-instance audit (trace every action to the specific instance that performed it). The agent server controls which instances receive agent tokens, providing centralized governance over a distributed agent fleet.¶

C.1.3. Why Every Agent Has a Person

Every agent acts on behalf of a person — the entity accountable for the agent's actions. AAuth enables a person server to maintain this link, making it visible and enforceable across the protocol. When present, the PS ensures there is always an accountable party for authorization decisions, audit, and liability.¶

C.1.4. Why the ps Claim in Agent Tokens

Resources need to discover the agent's PS to issue resource tokens in three-party mode. The ps claim in the agent token provides this discovery without requiring the AAuth-Mission header, which is only present when the agent is operating within a mission. This separates PS discovery from mission governance — an agent can use three-party mode without missions.¶

C.2.1. Why .json in Well-Known URIs

AAuth well-known metadata URIs use the .json extension (e.g., /.well-known/aauth-agent.json) rather than the extensionless convention used by OAuth and OpenID Connect. The .json extension makes the content type immediately obvious — no content negotiation is needed. More importantly, it enables static file hosting: a .json file served from GitHub Pages, S3, or a CDN works without server-side configuration. This aligns with AAuth's self-hosted agent model Appendix A, where an agent's metadata can be published as static files with no active server.¶

C.2.2. Why Standard HTTP Async Pattern

AAuth uses standard HTTP async semantics (202 Accepted, Location, Prefer: wait, Retry-After). This applies uniformly to all endpoints, aligns with RFC 7240, replaces OAuth device flow, supports headless agents, and enables clarification chat.¶

C.2.3. Why JSON Instead of Form-Encoded

JSON is the standard format for modern APIs. AAuth uses JSON for both request and response bodies.¶

C.2.4. Why No Authorization Code

AAuth eliminates authorization codes entirely. OAuth authorization codes require PKCE ([RFC7636]) to prevent interception attacks, adding complexity for both clients and servers. AAuth avoids the problem: the user redirect carries only the callback URL, which has no security value to an attacker. The auth token is delivered exclusively via polling, authenticated by the agent's HTTP Message Signature.¶

C.2.5. Why Callback URL Has No Security Role

Tokens never pass through the user's browser. The callback URL is purely a UX optimization.¶

C.2.6. Why No Refresh Token

AAuth has no refresh tokens. When an auth token expires, the agent obtains a fresh resource token and submits it through the standard authorization flow. This gives the resource a voice in every re-authorization — the resource can adjust scope, require step-up authorization, or deny access based on current policy. A separate refresh token would bypass the resource entirely, and is unnecessary given that the standard flow is a single additional request.¶

C.2.7. Why Reuse OpenID Connect Vocabulary

AAuth reuses OpenID Connect scope values, identity claims, and enterprise parameters. This lowers the adoption barrier.¶

C.3.1. Why a Separate Person Server

The PS is distinct from the AS because they serve different parties with different concerns. The PS represents the agent and its user — it handles consent, identity, mission governance, and audit. The AS represents the resource — it evaluates policy and issues tokens. Combining these into a single entity would conflate the interests of the requesting party with the interests of the resource owner, which is the same conflation that makes OAuth insufficient for cross-domain agent ecosystems.¶

C.3.2. Why Four Adoption Modes

The protocol supports identity-based, resource-managed (two-party), PS-managed (three-party), and federated (four-party) resource access modes, with agent governance as an orthogonal layer. A resource that only verifies agent signatures can start using AAuth today without deploying a PS or AS. As the ecosystem matures, the same resource can issue resource tokens to the agent's PS (three-party) and eventually deploy its own AS (four-party). Each mode is self-contained and useful — not a stepping stone to the "real" protocol. Agent governance (missions, permissions, audit) works independently of resource access modes.¶

C.3.3. Why Resource Tokens

In GNAP and OAuth, the resource server is a passive consumer of tokens — it verifies them but never produces signed artifacts. AAuth inverts this: the resource cryptographically asserts what is being requested by issuing a resource token that binds the resource's own identity, the agent's key thumbprint, the requested scope, and the mission context into a single signed JWT. This prevents confused deputy attacks — an attacker cannot substitute a different resource in the authorization flow because the resource token is signed by the resource. It also gives the resource a voice in every authorization and re-authorization, and provides a complete audit artifact linking the request to a specific resource, agent, scope, and mission.¶

C.3.4. Why Opaque AAuth-Access Tokens

In two-party mode, the resource returns an opaque wrapped token via the AAuth-Access header rather than a JWT auth token. This allows the resource to wrap its existing authorization infrastructure (OAuth access tokens, session tokens, etc.) without exposing internal structure. The token is bound to the AAuth signature — the agent includes it in the Authorization header as a covered component — so it cannot be stolen and replayed as a standalone bearer token.¶

C.3.5. Why Missions Are Not a Policy Language

Missions are intentionally not a machine-evaluable policy language. AAuth separates two kinds of authorization decisions:¶

• Deterministic policy is handled by scopes, resource tokens, and AS policy evaluation. These are mechanically evaluable — "does this agent have data.read scope for this resource?" A policy engine (Cedar, OPA/Rego, or any other) can answer this question consistently and automatically.¶

• Contextual governance is handled by missions, justifications, and clarification at the PS. These are the contextual decisions that policy engines cannot answer — "is booking a $10,000 flight reasonable for planning a weekend trip?" or "should this agent access the HR database given what it's trying to accomplish?" The mission description, the agent's justification for each resource access, and the clarification dialog between user and agent provide the context for these decisions.¶

Prior attempts to make authorization semantics machine-evaluable across domains have not scaled. OAuth Rich Authorization Requests (RAR) require clients and servers to agree on domain-specific type values and JSON structures — workable within a single API but combinatorially explosive across arbitrary services. UMA attempted cross-domain resource sharing with machine-readable permission tickets, but adoption stalled because resource owners, requesting parties, and authorization servers could not converge on shared semantics for what permissions meant across organizational boundaries. The fundamental problem is that the meaning of "appropriate access" is contextual, evolving, and domain-specific — it cannot be captured in a predefined vocabulary that all parties share.¶

Missions solve this differently. Rather than requiring all parties to agree on machine-evaluable semantics, AAuth concentrates governance evaluation at the PS — the only party with full context. The PS has the mission description, the user's identity and organizational context, the agent's justification for each request, the history of what the agent has done so far, and a channel to the user for clarification. No other party in the protocol has this context, and no predefined policy language can substitute for it.¶

This context can be presented to humans or to agents acting as decision-makers. The PS does not need to evaluate missions deterministically — it presents the mission context, the justification, and the resource request to whatever decision-maker is appropriate: a human reviewing a consent screen, an AI agent evaluating policy on behalf of an organization, or an automated system applying heuristics. As AI decision-making matures, governance can shift from human review to agent evaluation — without changing the protocol. AAuth standardizes how context is conveyed to the decision-maker; it does not prescribe how the decision is made.¶

The mission's description is Markdown because it represents human intent, not machine policy. The approved_tools array provides structured machine-evaluable elements where appropriate. Resources and access servers do not need the mission content — they enforce their own deterministic policies independently. The mission is a further restriction applied by the PS, and only the PS has sufficient context to evaluate it. Distributing mission semantics to other parties would be both a privacy leak and a false promise of enforcement, since those parties lack the context to evaluate the mission meaningfully.¶

C.3.6. Why Missions Have Only Two States

Missions are either active or terminated. There is no suspended state. A suspended state would require the agent to learn that the mission has resumed, but AAuth has no push channel from the PS to the agent — the agent can only poll. For short pauses (minutes), the deferred response mechanism already provides natural waiting via 202 polling. For long pauses (hours or more), the agent would need to poll indefinitely with no indication of when to stop, making suspension operationally equivalent to termination. Terminating the mission and creating a new one is cleaner — the PS retains the old mission's log for audit, and the new mission can be scoped appropriately for the changed circumstances that prompted the pause. This keeps mission lifecycle simple: a mission is alive until it is done.¶

C.3.7. Why Downstream Scope Is Not Constrained by Upstream Scope

In multi-hop scenarios, downstream authorization is intentionally not required to be a subset of upstream scopes. A flight booking API that calls a payment processor needs the payment processor to charge a card — an operation orthogonal to the upstream scope. Formal subset rules would prevent legitimate delegation chains. Instead, the PS evaluates each hop against the mission context, providing governance-based constraints that are more flexible than algebraic attenuation rules while maintaining a complete audit trail.¶

C.4.1. Why Not mTLS?

Mutual TLS (mTLS) authenticates the TLS connection, not individual HTTP requests. Different paths on the same resource may have different requirements — some paths may require no signature, others a signed request, others verified identity, and others an auth token. Per-request signatures allow resources to vary requirements by path. Additionally, mTLS requires PKI infrastructure (CA, certificate provisioning, revocation), cannot express progressive requirements, and is stripped by TLS-terminating proxies and CDNs. mTLS remains the right choice for infrastructure-level mutual authentication (e.g., service mesh). AAuth addresses application-level identity where progressive requirements and intermediary compatibility are needed.¶

C.4.2. Why Not DPoP?

DPoP ([RFC9449]) binds an existing OAuth access token to a key, preventing token theft. AAuth differs in that agents can establish identity from zero — no pre-existing token, no pre-registration. At the signature level ([I-D.hardt-httpbis-signature-key]), AAuth requires no tokens at all, only a signed request. DPoP has a single mode (prove you hold the key bound to this token), while AAuth supports progressive requirements from pseudonymous access through verified identity to authorized access with interactive consent. DPoP is the right choice for adding proof-of-possession to existing OAuth deployments.¶

C.4.3. Why Not Extend GNAP

GNAP ([RFC9635]) shares several motivations with AAuth — proof-of-possession by default, client identity without pre-registration, and async authorization. A natural question is whether AAuth's capabilities could be achieved as GNAP extensions rather than a new protocol. There are several reasons they cannot.¶

Resource tokens require an architectural change, not an extension. In GNAP, as in OAuth, the resource server is a passive consumer of tokens — it verifies them but never produces signed artifacts that the access server consumes. AAuth's resource tokens invert this: the resource cryptographically asserts what is being requested, binding its own identity, the agent's key thumbprint, and the requested scope into a signed JWT. Adding this to GNAP would require changing its core architectural assumption about the role of the resource server.¶

Interaction chaining requires a different continuation model. GNAP's continuation mechanism operates between a single client and a single access server. When a resource needs to access a downstream resource that requires user consent, GNAP has no mechanism for that consent requirement to propagate back through the call chain to the original user. Supporting this would require rethinking GNAP's continuation model to support multi-party propagation through intermediaries.¶

The federation model is fundamentally different. In GNAP, the client must discover and interact with each access server directly. AAuth's model — where the agent only ever talks to its PS, and the PS federates with resource ASes — is a different trust topology, not a configuration option. Retrofitting this into GNAP would produce a profile so constrained that it would be a distinct protocol in practice.¶

GNAP's generality is a liability for this use case. GNAP is designed to be maximally flexible — interaction modes, key proofing methods, token formats, and access structures are all pluggable. This means implementers must make dozens of profiling decisions before arriving at an interoperable system. AAuth makes these decisions prescriptively: one token format (JWT), one key proofing method (HTTP Message Signatures), one interaction pattern (interaction codes with polling), and one identity model (local@domain with HTTPS metadata). For the agent-to-resource ecosystem, this prescriptiveness is a feature — it enables interoperability without bilateral agreements.¶

In summary, AAuth's core innovations — resource-signed challenges, interaction chaining through multi-hop calls, PS-to-AS federation, mission-scoped authorization, and clarification chat during consent — are architectural choices that would require changing GNAP's foundations rather than extending them. The result would be a heavily constrained GNAP profile that shares little with other GNAP deployments.¶

C.4.4. Why Not Extend WWW-Authenticate?

WWW-Authenticate ([RFC9110], Section 11.6.1) tells the client which authentication scheme to use. Its challenge model is "present credentials" — it cannot express progressive requirements, authorization, or deferred approval, and it cannot appear in a 202 Accepted response.¶

AAuth-Requirement and Accept-Signature coexist with WWW-Authenticate. A 401 response MAY include multiple headers, and the client uses whichever it understands:¶

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
Accept-Signature: sig=("@method" "@authority" "@path");sigkey=uri

A 402 response MAY include WWW-Authenticate for payment (e.g., the Payment scheme defined by the Micropayment Protocol ([I-D.ryan-httpauth-payment])) alongside Accept-Signature for authentication or AAuth-Requirement for authorization:¶

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="x7Tg2pLq", method="example",
    request="eyJhbW91bnQiOiIxMDAw..."
Accept-Signature: sig=("@method" "@authority" "@path");sigkey=jkt

C.4.5. Why Not Extend OAuth?

OAuth 2.0 ([RFC6749]) was designed for delegated access — a user authorizes a pre-registered client to act on their behalf at a specific server. Extending OAuth for agent-to-resource authorization would require changing its foundational assumptions:¶

• Client identity: OAuth clients have no independent identity. A client_id is issued by each authorization server — it is meaningless outside that relationship. AAuth agents have self-sovereign identity (aauth:local@domain) verifiable by any party.¶
• Pre-registration: OAuth requires clients to register with each authorization server before use. AAuth agents call resources they have never contacted before — the first API call is the registration.¶
• Bearer tokens: OAuth access tokens are bearer credentials — anyone who holds the token can use it. AAuth binds every token to a signing key via HTTP Message Signatures — a stolen token is useless without the private key.¶
• No resource identity: OAuth does not cryptographically identify the resource. AAuth resources sign resource tokens, binding their identity to the authorization flow.¶
• No governance layer: OAuth has no concept of missions, permission endpoints, audit logging, or interaction relay. These would need to be built on top as extensions, losing the coherence of a protocol designed around them.¶
• No federation model: OAuth's authorization server is always the resource owner's server. AAuth separates the person server (user's choice) from the access server (resource's choice) and defines how they federate.¶

The Model Context Protocol (MCP) illustrates these limitations. MCP adopted OAuth 2.1 for agent-to-server authorization and immediately needed Dynamic Client Registration ([RFC7591]) because agents cannot pre-register with every server. But Dynamic Client Registration gives the agent a different client_id at each server — the agent still has no portable identity. Tokens are bearer credentials, so a stolen token grants full access. There is no resource identity — the server does not cryptographically prove who it is. There is no governance layer — no missions, no permission management, no audit trail. And the entire authorization model is per-server: each MCP server has its own authorization server, and the agent must discover and register with each one independently. MCP's experience demonstrates that OAuth can be made to work for the first API call, but it cannot provide the identity, governance, and federation that agents need as they operate across trust domains.¶

Rather than layer these changes onto OAuth — which would break backward compatibility and produce something unrecognizable — AAuth is a new protocol designed for the agent model from the ground up. AAuth complements OAuth: resources can wrap existing OAuth infrastructure behind the AAuth-Access token, and PSes can delegate user authentication to OpenID Connect providers.¶