Authentication

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 '@openagentid/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:

Authorization: OpenAgent <token>,
Authorization: Bearer <token>,
X-OpenAgent-Token,
detached signature headers.

It verifies the credential, checks scope and policy where configured, and returns a context object for handlers.

HTTP challenge-response

Server challenges

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

Agent signs

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

Agent retries

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

Server verifies

The server checks the signature, consumes the nonce, derives the DID, calls AEGIS 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:

Code	Meaning
`invalid_signature`	Signature does not verify against the provided public key
`expired_challenge`	Nonce or timestamp is outside the accepted window
`unknown_nonce`	Server did not issue the nonce
`invalid_session`	Bearer or OpenAgent session token is invalid
`insufficient_trust`	Route requires a higher trust tier
`rate_limited`	Trust-tier or policy rate limit was exceeded

Getting Started

Feature Stack

OpenAgent SDK

OpenAgent Client

OpenAgent Server

SDK facade

HTTP challenge-response

Canonical authorization header

Session headers

Transport posture

Errors

​SDK facade

​HTTP challenge-response

​Canonical authorization header

​Session headers

​Transport posture

​Errors

SDK facade

HTTP challenge-response

Canonical authorization header

Session headers

Transport posture

Errors