OpenAgent ID supports two day-one authentication paths:
  • the SDK facade, which verifies tokens and signatures through OpenAgent.authenticate(request);
  • the SDK-free HTTP challenge-response protocol, which lets any external agent prove key possession with Ed25519.

​
SDK facade

import { OpenAgent } from '@openagent/sdk';

const ctx = await OpenAgent.authenticate(request);

console.log(ctx.did);
console.log(ctx.scopes);
console.log(ctx.lineage);
The SDK searches the request for:
  1. Authorization: OpenAgent <token>,
  2. Authorization: Bearer <token>,
  3. X-OpenAgent-Token,
  4. detached signature headers.
It verifies the credential, checks scope and policy where configured, and returns a context object for handlers.

​
HTTP challenge-response

1

Server challenges

A protected route without valid auth returns 401 and WWW-Authenticate: OpenAgent challenge="<base64url>".
2

Agent signs

The agent decodes the challenge, applies JSON Canonicalization Scheme (JCS), and signs the canonical bytes.
3

Agent retries

The agent resends the original request with Authorization: OpenAgent <signature>.<public_key>.
4

Server verifies

The server checks the signature, consumes the nonce, derives the DID, calls AEGIS/L1feID as needed, and returns session headers.

​
Canonical authorization header

Authorization: OpenAgent <base64url(signature)>.<base64url(public_key)>
X-OpenAgent-Key-Type: ed25519
X-OpenAgent-Nonce: 24f9f0c1...

​
Session headers

X-OpenAgent-DID: did:key:z6Mk...
X-OpenAgent-Trust-Tier: anonymous
X-OpenAgent-Session: eyJhbGciOi...
X-OpenAgent-Session-Expires: 2026-03-21T12:15:00Z

​
Transport posture

HTTP is the normative launch binding. The v1.1.0 protocol defines abstract messages for additional transports, but Weave and WebSocket bindings are later-phase unless a deployment explicitly enables them.

​
Errors

Authentication failures use stable machine-readable codes. Common cases:
CodeMeaning
invalid_signatureSignature does not verify against the provided public key
expired_challengeNonce or timestamp is outside the accepted window
unknown_nonceServer did not issue the nonce
invalid_sessionBearer or OpenAgent session token is invalid
insufficient_trustRoute requires a higher trust tier
rate_limitedTrust-tier or policy rate limit was exceeded