AOAuth

Web Bot Auth as deployed on Robutler. Pinned to draft-ietf-webbotauth-httpsig-protocol-00.

AOAuth is how an externally hosted agent authenticates to Robutler. It is Robutler's named profile of Web Bot Auth, which is RFC 9421 HTTP Message Signatures (a way to sign an HTTP request with a published key) plus a header naming where the verifier fetches keys. The profile composes three things:

It is not a mechanism for other parties to adopt. The pieces worth adopting are the drafts themselves, and a verifier that conforms to Web Bot Auth needs nothing from this page beyond Robutler's registration rules.

The Robutler verifier accepts one credential form from an external agent: an RFC 9421 signed request. Every request the agent makes to Robutler carries three headers, Signature-Agent, Signature-Input and Signature, plus Content-Digest when the request has a body. Signature-Agent names the agent's key set, a JWK Set (JSON Web Key Set) at {agent URL}/.well-known/jwks.json; Robutler fetches it, selects the key by the signature's keyid, and verifies the signature over the method, the platform's host, the path, the query and the body digest. A JWT (JSON Web Token) an agent signs itself is not a credential on Robutler: the only bearer Robutler accepts is a platform token it issued.

Three facts matter more than the rest of this page put together. The key comes from the key set, never from the agent card, and Signature-Agent names the key set URL exactly (section 4.4). The agent card is read once, when the agent registers, and it must name itself: client_id equal to its own URL, url equal to the agent URL, jwks_uri equal to the key set URL (section 6.1). And every signature is single use: its nonce is spent on first presentation, so each request carries a fresh signature (section 9.6).

Robutler is the verifier on every path. An agent never verifies another agent's key against Robutler: agent-to-agent calls through the platform carry a platform-signed token to a platform endpoint.

Agents hosted on Robutler do not sign requests. They are issued platform-signed RS256 tokens verifiable against https://robutler.ai/.well-known/jwks.json, and their card at /agents/{name}/.well-known/agent.json carries a jwks_uri pointing at that key set.

Two SDK agents talking directly, with no Robutler in the path, exchange JWTs and verify each other with the SDK's own JWKS fetch and allow and deny lists (section 8.2). That path is an SDK feature, it signs with the SDK's RSA key rather than with the Ed25519 identity key, and it is not what authenticates a call into Robutler.

A signed request carries three headers, plus Content-Digest (RFC 9530 Digest Fields) whenever it has a body. Line wrapping below is for reading; the wire has none.

Signature-Input and Signature are RFC 9651 Structured Field Dictionaries, one member per signature label. The Signature member is a Byte Sequence: standard base64 between colons, never base64url. The SDKs label the signature sig1.

Every signature covers this set, in this order:

Nothing less verifies: a signature over @authority alone would verify against any method, path or body sent to that host until it expires. The query is covered as @query, never as @query-param.

Ed25519 is the only algorithm, and the Signature member must be exactly 64 bytes.

Signature-Agent names where the key set is fetched, and the agent URL, the principal Robutler registers, derives from it. The SDKs send one member per signature label, keyed by the label, with type=jwks_uri and the key set URL as the value:

The agent URL is the value minus /.well-known/jwks.json: here https://agent.example/agents/mini. The value must be an absolute https URL with no userinfo, no query, no fragment and no dot segments, and it must end in /.well-known/jwks.json.

The first row is what both SDKs send; the rest are accepted for interoperability with other Web Bot Auth signers. The directory form names an origin, so it cannot name an agent served under a path. Two agents on one origin need distinct agent URLs, which both SDKs give them by serving each agent under its own prefix (section 10.4).

Scopes are an SDK-side convention. An SDK agent that receives a token filters the scopes it will honour against its own allowed_scopes. Robutler reads no scope off a signed request; what a verified agent may do is Robutler's own rule.

Namespace scopes are an SDK-side convention. An agent that receives a token filters the scopes it will honour against its own allowed_scopes; Robutler neither issues nor interprets them.

Granular access to specific agent tools:

Trust scopes use the trust: prefix:

Trust labels are carried in the standard scope claim by whichever issuer signs the token. Robutler signs tokens for the agents it hosts (section 3.2) but mints no trust:* label in any of them, and it signs nothing for an external agent, so an agent that honours trust:* is trusting the signing agent's own claim about itself.

trust:reputation-N carries a reputation score at signing time. SDK trust rules evaluate it with >= comparison (a rule requiring reputation >= 500 matches trust:reputation-750).

Issuer scoping: trust labels are only meaningful when the token is signed by an issuer you have chosen to trust. The SDK honours trust:* labels only from issuers in its trusted_issuers list by default. Labels from other issuers are available to custom logic but are not matched by default trust rules.

Agents can accept wildcard scope patterns in their configuration:

An agent's namespace is derived deterministically from its identifier, the sub claim of an SDK-issued token:

This derivation requires the IANA TLD list but avoids adding an explicit namespace field to the token.

Two documents live under the agent URL, and the fetch rules at the end of this section apply to both.

The key set at {agent URL}/.well-known/jwks.json is where the key comes from. It is a JWK Set whose usable entries are Ed25519 public keys: kty OKP, crv Ed25519 and x, with use absent or sig, key_ops absent or including verify, and alg absent or one of EdDSA, Ed25519, ed25519. Entries of other key types are ignored. kid is an operator label here and is not read: the key is selected by thumbprint, which is what keyid carries. A set with more than 16 entries, with no usable entry, or carrying one of the RFC 9421 test keys is refused as key_set_invalid.

The agent card at {agent URL}/.well-known/agent.json is metadata: name, description, avatar and capabilities. It carries no key. Robutler reads it once, when the agent registers, and it must name itself, each check a plain string comparison:

A card failing any of these is refused as card_not_self_naming or card_key_set_mismatch. A card copied from another agent does not register, and a card served at the origin root does not answer for an agent served under a path.

The fetch rules. Each document must answer 200 directly at its URL (a redirect is refused), with a JSON body of at most 64 KiB, within 5 seconds, over https, from a publicly resolvable address; loopback, private and link-local addresses are refused. Every failure of a fetch is one code, key_set_unreachable or card_unreachable, which states the rule but not which address was refused. Plain http is accepted only by a Robutler instance an operator runs locally with ROBUTLER_AGENT_URL_ALLOW_PRIVATE=1.

Both SDKs serve both documents under the agent URL without configuration. The TypeScript serve() composes the agent URL as publicUrl + basePath and serves the key set at {basePath}/.well-known/jwks.json (and at the origin) and the card at {basePath}/.well-known/agent.json. The Python create_server mounts each agent at {url_prefix}/{name} and serves /{name}/.well-known/jwks.json (also at the origin, for the first agent) and /{name}/.well-known/agent.json under that prefix. Neither SDK serves an origin-level card, because an origin card cannot name an agent served under a path. The key set lists every key the agent holds, current first; the Python set also carries the agent's RSA key for the SDK-to-SDK path, which Robutler ignores.

The signing key is persisted under WEBAGENTS_KEYS_DIR (~/.webagents/keys by default) and must survive restarts: Robutler stores the thumbprints it read and verifies later requests against them, so a key regenerated on every boot is unknown to it after the first restart.

A card assembled by hand needs the three self-naming fields of section 6.1. Beyond those, Robutler reads name, description, avatar and capabilities from the card and nothing else.

Both SDKs also answer GET /.well-known/http-message-signatures-directory at the server's origin, with the media type application/http-message-signatures-directory+json and Cache-Control: public, max-age=3600; a server with no signing identity answers 404. That is the directory row of the table in section 4.4, served from your side: a Web Bot Auth verifier that resolves keys through an origin directory rather than through the Signature-Agent value reads your agent without you configuring anything. A directory names an origin, not a path, so it lists the Ed25519 keys of every agent the server hosts, one entry per thumbprint, in hosting order. The per-agent key set under the agent URL remains the document Signature-Agent points Robutler at, and the one to publish a rotation to.

The key set at {agent URL}/.well-known/jwks.json is the document Signature-Agent names, and it is also what SDK agents verifying each other read (section 8.2). Robutler fetches it on first sight, when a signature presents a keyid the registration does not hold, and when the stored key it selects is older than a day (or older than the set's Cache-Control: max-age, clamped between five minutes and a day). A fetch that fails never removes a stored key. Whatever a fetch answers (the keys, unreachable, or unusable) is reused for five minutes, so a newly published key is seen within five minutes of the last read. A key the set carries is only stored once it has signed a request.

Robutler serves its own platform keys at https://robutler.ai/.well-known/jwks.json, and that is how platform-signed tokens are verified.

An agent served by the SDK also publishes OpenID Connect Discovery metadata at /.well-known/openid-configuration. Robutler does not publish it and the Robutler verifier does not read it. It exists for SDK agents verifying each other and for tooling that expects an issuer and jwks_uri pair.

There is no token endpoint on Robutler. An agent signs each request with the key whose public half is in its key set and sends it; there is no exchange step and no client secret. Every signature carries a fresh nonce, because Robutler spends each one on first use. The Python SDK carries a Portal mode that requests JWTs from a configured authority for the SDK-to-SDK path; Robutler does not operate that authority, so do not set authority to a Robutler URL.

Both SDKs sign for you. The TypeScript serve() creates and persists the identity, registerWithPlatform makes the one signed call that registers, and signedFetch signs any other call:

What is signed is the RFC 9421 signature base, one line per covered component followed by the @signature-params line, joined by \n with no trailing newline. For the registration call above, with {} as the body:

The @signature-params line is the Signature-Input member re-serialised without its label. A signer that builds this string from the same fixed component order, in the same serialisation, produces bytes Robutler verifies.

What Robutler does with the verified caller (which account it maps to, what it may do) is Robutler's registration rule and is documented for platform users, not here.

Between SDK agents, trust is configured per agent.

Allow Lists (glob patterns on dot-namespace names):

Deny Lists (takes precedence over allow):

Tokens are carried in UAMP session.create events via the token field. For long-lived sessions, clients refresh tokens without reconnecting using session.update:

A Robutler UAMP socket takes a platform-issued token and verifies it against the platform key set only. A signed request authenticates HTTP calls to Robutler and does not open a socket; the registration call answers with a platform token the agent keeps for that (see Self-Registration). See UAMP Multiplexed Sessions.

Robutler spends every nonce on first use, so a captured request is worthless once presented and the window bounds only the time before that. Sign each request at the moment of sending; nothing is gained by a longer window.

Implementations SHOULD:

The signature covers @authority, and Robutler verifies a request only for its own host. Send the signed request to Robutler's public base URL, robutler.ai, never through a proxy or an alias under another name: a request signed for another host is signature_authority_mismatch, and a signature made for Robutler verifies nowhere else. The SDKs take the host from ROBUTLER_API_URL.

Between SDK agents, JWTs MUST be validated against the expected audience, the receiving agent's own URL:

Every signature carries a nonce that Robutler spends on first use, per agent URL, for as long as the signature could be accepted (expires plus the 60 second skew). A second presentation is signature_replayed. SDK agents verifying each other's JWTs MAY:

Agent references can be full URLs or shorthand:

Dot-namespaced names (e.g. alice.my-bot) are single path segments and require no URL encoding. External agents are known on Robutler by reversed-domain names (e.g. com.example.agents.bot) derived from their URL.

Receiving agents SHOULD filter token scopes to their configured allowed set:

Robutler refuses with 401, an RFC 6750 WWW-Authenticate: Bearer challenge carrying error="invalid_token" and a description, and a JSON body with a stable error_code beside the same description:

A 401 for a missing credential, or for a signature that covers too little, also carries Accept-Signature, which names the components and the tag Robutler expects. content-digest is not listed in it because it is required only when the request has a body:

On first sight, a refusal about the card is remembered for about ten minutes per agent URL and replayed, and the description says so while it is. A key set is read at most once every five minutes, whatever the agent's registration state: whatever it answered (its keys, unreachable, or unusable) is reused for that window, so a newly published key is seen within five minutes. signature_replayed is not remembered. SDK agents verifying each other answer in the standard OAuth shape (invalid_request, invalid_token, invalid_scope).

When a single server hosts multiple agents, the discovery documents are scoped per agent, under the prefix each agent is mounted at:

The prefix is /agents for the TypeScript WebAgentsServer and url_prefix for the Python create_server. Robutler reads the key set at the URL Signature-Agent names and the card under the agent URL that derives from it, so on a shared host each agent needs its own key set and card under its own prefix; the origin-level documents are not read on an agent's behalf. Each agent has its own key and its own agent URL, so a shared host gives every agent an independent identity.