AAuth Bootstrap

1.1. In Scope

• SaaS browser agents (vendor-operated agent server).¶
• SaaS mobile agents (vendor-operated agent server).¶
• B2B SaaS agents (organization's PS, vendor's agent server).¶

1.2. Out of Scope

• Self-hosted agents (including developer AI agents). These self-issue agent tokens from durable local keys published in their own JWKS.¶
• Command-line tools. Agent identity is established by deployment tooling that registers a public key with a JWKS-hosting endpoint.¶
• Server workloads and headless services. These use platform attestation mechanisms such as SPIFFE, WIMSE, or cloud instance identity.¶
• Organizational agents operating within a pre-established PS-AS trust relationship with administrative enrollment.¶

3.1. Terms Reused From AAuth Protocol

The following terms are defined in [I-D.hardt-aauth-protocol] and are used in this document with the same meaning. Summaries are provided for convenience; the referenced specification is authoritative.¶

• Person: The user or organization on whose behalf an agent acts. Referred to in this document as "the user".¶
• Agent: An HTTP client acting on behalf of a person, identified by an aauth:local@domain URI.¶
• Agent Server: A server that manages agent identity and issues agent tokens. In the context of this document, the agent server is operated by the vendor whose software the user is running.¶
• Person Server (PS): A server that represents the person to the rest of the protocol. In the context of this document, the PS vouches for the user to the agent server during bootstrap.¶
• Resource: A server that protects access to its APIs. Not directly involved in bootstrap.¶
• Agent Token: A JWT issued by an agent server to establish the agent's identity.¶
• Resource Token: A JWT issued by a resource (or, in bootstrap, by the agent server acting as resource) describing the access an agent needs.¶
• Auth Token: A JWT issued by a PS or AS granting an agent access to a resource.¶
• Interaction: User authentication or consent at an interaction endpoint, triggered when a server returns 202 Accepted with requirement=interaction.¶

3.2. Terms Reused From HTTP Signature Keys

The following signature schemes are defined in [I-D.hardt-httpbis-signature-key] and used in this document without modification:¶

• hwk scheme: Conveys a public key inline in the Signature-Key header.¶
• jkt-jwt scheme: Chains a JWT signed by one key (e.g., a durable enclave key) to authorize a second key (e.g., an ephemeral HTTP signing key).¶
• jwt scheme: Conveys a JWT (e.g., an agent token) that names the signing key.¶

3.3. Terms Defined in This Document

• Bootstrap: The PS-mediated ceremony defined in this document by which a SaaS or B2B agent obtains its initial agent token. Distinct from the developer-side ceremonies used by self-hosted agents and from platform attestation enrollment.¶
• Ephemeral Key: An HTTP signing key generated by the agent whose lifetime is bounded by the agent token. Typically hours to a day, not per-request.¶
• Durable Key: A platform-protected key whose lifetime is bounded by the application install. Typically months to years. On mobile, this is an enclave-protected key identified by a JWK thumbprint (urn:jkt).¶
• bootstrap_token: A short-lived JWT issued by the PS, directed at an agent server, and bound to an agent's ephemeral key via a cnf claim. Defined in Section 8.4.¶
• Binding: The one-to-one association (ps_url, user_sub) -> aauth:local@<agent-server-domain> recorded by the agent server at the end of bootstrap, together with the device credentials associated with it.¶
• Device Credential: A credential held by the agent server and associated with a binding, used to authenticate renewal requests without re-involving the PS. A WebAuthn credential ID on browsers or an enclave-key thumbprint (urn:jkt:sha-256:<thumbprint>) on mobile.¶

7.1. Request

The agent issues a GET request with the ceremony type as a query parameter:¶

GET /webauthn?type=create HTTP/1.1
Host: agent-server.example

or¶

GET /webauthn?type=get HTTP/1.1
Host: agent-server.example

Query parameters:¶

• type (REQUIRED). Either create (for bootstrap registration) or get (for refresh assertion).¶

The request is unsigned. The agent MUST NOT include user identifiers on the challenge request.¶

7.2. Response

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

{
  "challenge": "<base64url random bytes>",
  "creation_options": {
    "rp": { "id": "agent-server.example", "name": "Example AI Assistant" },
    "pubKeyCredParams": [{ "type": "public-key", "alg": -7 }, ...],
    "authenticatorSelection": { ... },
    "attestation": "none"
  }
}

Response members:¶

• challenge (REQUIRED). Server-generated random value of at least 16 bytes, base64url-encoded without padding. The agent server MUST store the challenge in a single-use, time-limited registry. The challenge SHOULD expire within 5 minutes.¶
• creation_options (REQUIRED when type=create). The non-user portions of a WebAuthn PublicKeyCredentialCreationOptions object ([WebAuthn]): rp, pubKeyCredParams, authenticatorSelection, attestation, timeout, and related server-decided fields. The agent fills in the challenge field from this response and fills in the user field from the bootstrap_token (using bootstrap_token.sub as user.id). MUST be absent when type=get.¶

The response MUST NOT include user-identifying information. The agent server MUST NOT bind the challenge to a particular user in its issuing state; user context enters only when the ceremony result is submitted.¶

8.1. Key Generation

The agent generates an ephemeral signing key.¶

On mobile platforms, the agent also has (or generates on first install) a durable enclave-protected key with a stable JWK thumbprint of the form urn:jkt:sha-256:<thumbprint>.¶

On browsers and command-line environments, only the ephemeral key exists.¶

8.2. Request to PS /bootstrap

The agent sends an HTTP request to the PS's /bootstrap endpoint signed under the hwk scheme ([I-D.hardt-httpbis-signature-key]) using the ephemeral key:¶

POST /bootstrap HTTP/1.1
Host: ps.example
Signature-Input: sig=...
Signature: sig=...
Signature-Key: sig=hwk;kty="OKP";crv="Ed25519";x="<ephemeral-pubkey>"
Content-Type: application/json

{
  "agent_server": "https://agent-server.example"
}

The request body is a JSON object with the following members:¶

• agent_server (REQUIRED). The HTTPS URL identifying the agent server that will mint the agent identity. This value is placed in the aud claim of the issued bootstrap_token. This document uses the parameter name agent_server to align with the "Agent Server" terminology of [I-D.hardt-aauth-protocol]; implementations MUST NOT use alternative names such as audience or client_id for this field.¶
• domain_hint (OPTIONAL). Identifies which of the user's identities at this PS should be used when the user has more than one (for example a personal identity and a work identity). The value is a DNS domain, as defined in [OpenID.EnterpriseExtensions]. When present, the PS SHOULD select the identity associated with the given domain without prompting the user to choose. When absent and more than one identity is available, the PS MAY prompt the user to choose.¶
• login_hint (OPTIONAL). A hint as defined in [OpenID.EnterpriseExtensions] identifying the user (for example an email address) to help the PS select the appropriate identity.¶
• tenant (OPTIONAL). Organizational tenant identifier from [OpenID.EnterpriseExtensions]. See Section 14.¶

Additional parameters from [OpenID.EnterpriseExtensions] MAY be included to select an organizational identity context.¶

8.3. Interaction Response

The PS responds with an interaction requirement:¶

HTTP/1.1 202 Accepted
AAuth-Requirement: requirement=interaction
Location: /bootstrap/pending/<id>

The agent directs the user to the interaction URL. The PS authenticates the user and presents a consent screen asking the user to allow the agent server to establish an account bound to the user's identity at this PS. No identity claims are released at this step; claims flow through the standard AAuth three-party flow after bootstrap completes.¶

The consent screen SHOULD display the agent server's domain, name, and logo as retrieved from the agent server's /.well-known/aauth-agent.json metadata document. The user approves or denies the request.¶

The agent polls the pending URL indicated by Location until the interaction completes.¶

8.4. bootstrap_token Issuance

On successful user approval, the PS returns a bootstrap_token from the pending URL.¶

The bootstrap_token is a signed JWT with the following structure.¶

8.5. Request to Agent Server /bootstrap

Before calling bootstrap_endpoint, the agent performs the attestation ceremony appropriate to its platform. See Section 9 for the ceremony details and for the logic by which the platform is chosen. The attestation result is carried in the POST body.¶

The agent sends a single POST to bootstrap_endpoint:¶

POST /bootstrap HTTP/1.1
Host: agent-server.example
Signature-Input: sig=...
Signature: sig=...
Signature-Key: sig=<scheme>
Content-Type: application/json

{
  "bootstrap_token": "<jwt>",
  "attestation": {
    "type": "<attestation type>",
    ...
  }
}

The HTTP Message Signature scheme is determined by the platform:¶

• Browser clients use hwk with the agent's ephemeral key.¶
• Mobile clients use jkt-jwt ([I-D.hardt-httpbis-signature-key]), where the JWT header references the enclave key and the JWT payload's cnf.jwk is the ephemeral public key. The ephemeral key signs the HTTP message.¶

Request body members:¶

• bootstrap_token (REQUIRED). The JWT received from the PS.¶
• attestation (REQUIRED). The attestation result, whose shape is defined by the ceremony described in Section 9. The type field identifies the ceremony (e.g., webauthn, app-attest, play-integrity) and MUST match the scheme implied by the HTTP signature.¶

On receiving the request, the agent server MUST:¶

1. Verify the HTTP Message Signature as defined in [I-D.hardt-httpbis-signature-key].¶
2. Resolve and validate the bootstrap_token signature by fetching the PS's JWKS using iss and dwk.¶
3. Verify that bootstrap_token.aud equals the agent server's own URL.¶
4. Verify that bootstrap_token.cnf.jwk matches the ephemeral public key used to sign the HTTP request.¶
5. Verify iat, exp, and jti per standard JWT rules; reject replays by jti.¶
6. Verify the attestation per the rules of the indicated ceremony in Section 9, including that any ceremony challenge or nonce matches one issued by the agent server and has not expired or been consumed. Mark the ceremony challenge as consumed.¶
7. Create or look up the binding Section 8.6.¶
8. Store the device credential derived from the attestation (a WebAuthn credential ID for browsers, or the enclave key thumbprint for mobile) on the binding.¶
9. Issue the agent token Section 8.7.¶

If bootstrap_token verification fails, the agent server MUST respond 400 Bad Request. If attestation verification fails, the agent server MUST respond 401 Unauthorized.¶

8.6. Binding Creation

The agent server looks up or creates a binding keyed by (bootstrap_token.iss, bootstrap_token.sub):¶

(ps_url, user_sub) -> aauth:local@<agent-server-domain>

The binding is one-to-one: the same user at the same PS at the same agent server MUST map to the same aauth:local@domain identity, regardless of device.¶

The agent server stores the device credential obtained during attestation (a WebAuthn credential ID, or a urn:jkt:sha-256:<enclave> thumbprint) against the binding. Multiple device credentials MAY be associated with a single binding.¶

8.7. Token Response

The agent server returns an agent token:¶

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

{
  "agent_token": "<jwt>"
}

The agent_token is a JWT as defined in [I-D.hardt-aauth-protocol] with:¶

• typ: aa-agent+jwt.¶
• iss: The agent server URL.¶
• dwk: aauth-agent.json.¶
• sub: The aauth:local@<agent-server-domain> identity from the binding.¶
• ps: The PS URL (from bootstrap_token.iss).¶
• cnf.jwk: The agent's ephemeral public key.¶

The agent server does not issue a resource_token at bootstrap. If the agent server needs to release user identity claims to itself (for example to populate a user profile page), it follows the standard AAuth Protocol three-party flow after bootstrap completes.¶

8.8. Bootstrap Completion

Once the agent holds the agent_token, it SHOULD announce its new agent identity to the PS so the PS can bind the identity to the user within the PS's bootstrap record. The agent SHOULD perform this announcement before rotating its ephemeral key (that is, before any call to refresh_endpoint), because the PS correlates the announcement to the bootstrap record by the ephemeral key's thumbprint.¶

POST /bootstrap HTTP/1.1
Host: ps.example
Signature-Input: sig=...
Signature: sig=...
Signature-Key: sig=jwt;jwt="<agent_token>"
Content-Length: 0

9.1. Ceremony Selection

The agent selects the ceremony from its runtime platform. The agent server determines which ceremony to expect from the HTTP signature scheme on the bootstrap_endpoint or refresh_endpoint POST.¶

An agent server that supports browser clients MUST publish webauthn_endpoint in its metadata Section 6. Mobile clients obtain ceremony nonces through platform-specific means; no corresponding metadata field is defined by this document because the ceremony details are platform-specific.¶

Agents that cannot perform any of the ceremonies above (for example, a command-line tool with no platform authenticator and no enclave) are outside the scope of this specification.¶

9.2. Browser: WebAuthn

Browser clients use the same webauthn_endpoint Section 7 for both bootstrap (type=create) and renewal (type=get). The ceremony result is carried in the POST body to bootstrap_endpoint or refresh_endpoint.¶

GET /webauthn?type=create HTTP/1.1
Host: agent-server.example

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

{
  "challenge": "<base64url random bytes>",
  "creation_options": {
    "rp": { "id": "agent-server.example", "name": "Example AI Assistant" },
    "pubKeyCredParams": [
      { "type": "public-key", "alg": -7 },
      { "type": "public-key", "alg": -257 }
    ],
    "authenticatorSelection": {
      "residentKey": "required",
      "userVerification": "preferred"
    },
    "attestation": "none"
  }
}

POST /bootstrap HTTP/1.1
Host: agent-server.example
Signature-Input: sig=...
Signature: sig=...
Signature-Key: sig=hwk;kty="OKP";crv="Ed25519";x="<ephemeral-pubkey>"
Content-Type: application/json

{
  "bootstrap_token": "<jwt>",
  "attestation": {
    "type": "webauthn",
    "credential": {
      "id": "<base64url credential id>",
      "rawId": "<base64url>",
      "response": {
        "clientDataJSON": "<base64url>",
        "attestationObject": "<base64url>"
      },
      "type": "public-key"
    }
  }
}

GET /webauthn?type=get HTTP/1.1
Host: agent-server.example

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

{
  "challenge": "<base64url random bytes>"
}

POST /refresh HTTP/1.1
Host: agent-server.example
Signature-Input: sig=...
Signature: sig=...
Signature-Key: sig=hwk;kty="OKP";crv="Ed25519";x="<new-ephemeral-pubkey>"
Content-Type: application/json

{
  "attestation": {
    "type": "webauthn",
    "credential": {
      "id": "<base64url credential id>",
      "rawId": "<base64url>",
      "response": {
        "clientDataJSON": "<base64url>",
        "authenticatorData": "<base64url>",
        "signature": "<base64url>",
        "userHandle": "<base64url>"
      },
      "type": "public-key"
    }
  }
}

9.3. Mobile: Platform Attestation and Enclave Proof

Mobile clients use App Attest (iOS) or Play Integrity (Android) at bootstrap to enroll the enclave key as the device credential. At renewal, the enclave key signature in the jkt-jwt HTTP Message Signature is itself sufficient proof; no additional ceremony is required.¶

POST /bootstrap HTTP/1.1
Host: agent-server.example
Signature-Input: sig=...
Signature: sig=...
Signature-Key: sig=jkt-jwt;jwt="<jkt-jwt-token>"
Content-Type: application/json

{
  "bootstrap_token": "<jwt>",
  "attestation": {
    "type": "app-attest",
    "key_id": "<base64url>",
    "attestation_object": "<base64url>",
    "client_data_hash": "<base64url>"
  }
}

{
  "type": "play-integrity",
  "integrity_token": "<JWS-encoded attestation>"
}

POST /refresh HTTP/1.1
Host: agent-server.example
Signature-Input: sig=...
Signature: sig=...
Signature-Key: sig=jkt-jwt;jwt="<jkt-jwt-token>"

11.1. Renewal Flow

Before calling refresh_endpoint, the agent performs the renewal attestation ceremony appropriate to its platform. See Section 9 for the ceremony details. The ceremony result, if any, is carried in the POST body.¶

POST /refresh HTTP/1.1
Host: agent-server.example
Signature-Input: sig=...
Signature: sig=...
Signature-Key: sig=<scheme>
Content-Type: application/json

{
  "attestation": {
    "type": "<attestation type>",
    ...
  }
}

The HTTP Message Signature scheme is determined by the platform:¶

• Browser clients use hwk with a newly generated ephemeral key.¶
• Mobile clients use jkt-jwt ([I-D.hardt-httpbis-signature-key]), where the enclave key signs a jkt-jwt binding a newly generated ephemeral key; the ephemeral key signs the HTTP message. For mobile, the request body MAY be empty because the jkt-jwt signature itself proves possession of the device credential.¶

Request body members:¶

• attestation (REQUIRED for browser clients; omitted for mobile clients). The assertion result defined by the renewal ceremony in Section 9.¶

On receiving the request, the agent server MUST:¶

1. Verify the HTTP Message Signature.¶

2. Look up the binding:¶

   • For browser clients, by the credential ID (rawId) in the WebAuthn assertion.¶
   • For mobile clients, by the enclave key thumbprint (urn:jkt:sha-256:<thumbprint>) derived from the jkt-jwt header.¶
3. Verify the renewal attestation per the rules of the indicated ceremony in Section 9, including that any ceremony challenge matches one it issued and has not expired or been consumed. Mark the challenge as consumed.¶
4. Issue a fresh agent token bound to the new ephemeral key.¶

11.2. Refresh Response

On success, the agent server returns:¶

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

{
  "agent_token": "<jwt>"
}

The agent_token has the same structure as in Section 8.7 but bound to the new ephemeral key.¶

11.3. Renewal Failure

Renewal MUST fail in the following conditions. The agent server MUST respond with 401 Unauthorized (for credential failures) or 404 Not Found (for missing bindings), and the agent MUST repeat the full PS-mediated bootstrap flow from Section 8:¶

• The enclave key has been regenerated (for example, after mobile reinstall) and the urn:jkt is no longer recognized.¶
• The WebAuthn credential is no longer usable (for example, browser storage cleared or hardware key removed).¶
• The binding has been revoked at the agent server.¶
• The PS has stopped vouching for the user (for example, B2B deprovisioning). In this case the subsequent PS /bootstrap call will fail at the interaction step, and the agent will be unable to re-establish the binding.¶

15.1. bootstrap_token Replay

The bootstrap_token carries a cnf claim binding it to the agent's ephemeral public key. Possession of the token alone is insufficient; the holder MUST also control the corresponding private key. Agent servers MUST reject bootstrap_tokens that are not accompanied by an HTTP request signed with the key named in cnf.jwk, and MUST reject replay by jti.¶

15.2. Consent Phishing

The user sees the agent server's domain, name, and logo at the PS consent screen. This relies on user recognition of the agent server. The PS SHOULD retrieve the agent server's display metadata from its /.well-known/aauth-agent.json document and present it at the consent screen.¶

15.3. Key-to-User Binding Without Attestation

The bootstrap flow as specified relies on platform attestation at the agent server step. Environments without a platform attestation mechanism cannot safely use this flow because a remote process may impersonate a local user by relaying ephemeral keys through them. This is the reason command-line tools are out of scope.¶

15.4. Enclave Key Compromise

On mobile, compromise of the enclave key breaks the chain of delegated ephemeral keys. Implementations SHOULD use the shortest practical jkt-jwt lifetimes.¶

15.5. Agent Server Compromise

Compromise of an agent server breaks all agent identities minted by that server. Bootstrap does not introduce this risk, but centralizes it at the agent server.¶

15.6. PS Compromise

The PS is already a high-value target in [I-D.hardt-aauth-protocol]. Bootstrap does not change the risk profile, but makes the PS load-bearing for agent identity creation.¶

15.7. Bootstrap Completion Announcement

The announcement POST to the PS Section 8.8 is bound to possession of the agent's ephemeral key plus a signed agent_token issued to that key. An attacker would need both the ephemeral private key and a valid agent_token for the target aauth identifier. These are the same credentials that protect the rest of bootstrap; the announcement introduces no new attack surface.¶

16.1. Directed User Identifiers

The bootstrap_token.sub claim MUST be a pairwise user identifier directed at the agent server. This prevents cross-vendor correlation of users across different agent servers.¶

16.2. Mobile Enclave Identity

The PS sees only the ephemeral hwk key. The agent server sees the jkt-jwt carrying the enclave identity. The PS therefore cannot track a device across bootstraps at different agent servers.¶

16.3. Out-of-Band Consent Channel

The user communication channel held by the PS after first bootstrap is privacy-sensitive. PS implementations SHOULD document their user communication practices.¶

16.4. Agent Identifier Registry at the PS

After bootstrap completion Section 8.8, the PS knows the aauth:local@domain identifier of each agent the user has bootstrapped. This supports user-facing features such as a dashboard of connected agents and targeted revocation ("disconnect from agent X"). PS implementations SHOULD make this list visible to the user.¶

17.1. Media Type Registration

This document requests registration of the following media type in the IANA Media Types registry:¶

• application/aa-bootstrap+jwt: JWT used by the AAuth Bootstrap protocol.¶

17.2. JWT Claims

This document does not introduce new JWT claims. The bootstrap_token uses existing claims and those defined in [I-D.hardt-aauth-protocol].¶

17.3. AAuth Agent Server Metadata Registration

This document registers the following parameters in the AAuth Agent Server Metadata registry established by [I-D.hardt-aauth-protocol]:¶