OpenAgent supports two related authentication surfaces:
  1. The SDK facade: OpenAgent.authenticate(request) verifies tokens or signatures and returns a typed context.
  2. The protocol binding: an HTTP challenge-response flow that external agents can implement without any OpenAgent SDK.

​
Normative HTTP flow

1

Unauthenticated request

The agent calls a protected endpoint without a valid session.
2

Server returns challenge

The server responds 401 with WWW-Authenticate: OpenAgent challenge="<base64url>".
3

Agent signs challenge

The agent JCS-canonicalizes the challenge JSON and signs it with Ed25519.
4

Agent retries

The request includes Authorization: OpenAgent <base64url(signature)>.<base64url(public_key)> and X-OpenAgent-Key-Type: ed25519.
5

Server verifies and issues session

The server consumes the nonce, derives the DID, computes trust tier, and returns session metadata.

​
Canonical headers

Successful responses can include:

​
SDK authenticate path

The public SDK also supports direct token verification:
The SDK looks for Authorization: OpenAgent <token>, Authorization: Bearer <token>, X-OpenAgent-Token, and oa_token query parameters, then returns a context with DID, scopes, lineage, expiry, and policy results.

​
Future bindings

The v1.1.0 spec defines transport-agnostic message types. HTTP is the normative day-one binding. Weave and WebSocket bindings are designed for later phases and should not be treated as launch-ready unless a deployment explicitly enables them.