Verifying a Token

verifyAgentToken is the public contract. Everything else in this package — the account wrapper, the three framework bindings — is a convenience layer on top of it, and a partner who depends on the core alone is insulated from all of them.

It checks a token, against the keys we publish, and returns either the verified identity or a code you can branch on. It does not call a database, and it does not call us.

import { verifyAgentToken } from "@agentonboard/sdk";

const result = await verifyAgentToken({
  token,        // the raw JWT, with or without a `Bearer ` prefix
  audience: "notes.com",
});

What it checksCopy Anchor Link

The token is a bearer credential with a 5-minute lifetime. That is the whole of its replay story: the SDK records no token ids, so a token presented twice inside its window verifies both times. Treat it as a bearer token — TLS only, never logged.

OptionsCopy Anchor Link

interface VerifyAgentTokenOptions {
  token: string;                  // required
  audience: string;               // required
  issuer?: string;
  jwksUrl?: string;
  jwks?: JSONWebKeySet;
  fetchJwks?: (url: string) => Promise<unknown>;
  clockToleranceSeconds?: number;
}

AON_ISSUERCopy Anchor Link

AON_ISSUER is the only environment variable the SDK reads, and it is the default for issuer. It is compared against the token's iss claim and it is the host the keys are fetched from.

jwks and fetchJwksCopy Anchor Link

jwks takes a parsed key set and bypasses the URL entirely. It is how an air-gapped or self-hosted issuer works, and how a test supplies keys with no network at all. It wins over fetchJwks when both are set: supplying keys is the stronger statement, and it is the only path that touches no network.

fetchJwks replaces the host runtime's fetch for the key-set request — a pinned egress proxy, a cached copy, a test with no network. It is called with the same URL that would have been fetched and is expected to resolve to a parsed JWKS. The shape check still applies, and the last-known-good fallback still applies.

const result = await verifyAgentToken({
  token,
  audience: "notes.com",
  fetchJwks: async (url) => {
    try {
      const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
      if (!res.ok) throw new Error(`JWKS endpoint responded ${res.status}`);
      return await res.json();
    } catch (err) {
      // The SDK will not publish this. Log it where you can see it.
      logger.error({ err, url }, "key set retrieval failed");
      throw err;
    }
  },
});

AudienceCopy Anchor Link

Your audience option is normalized to a hostname: trimmed, lowercased, and stripped of any scheme, path, and port. localhost and 127.0.0.1 keep their port, because a local deployment's port is part of its identity.

The token's aud claim is then compared to that normalized value exactly, and case-sensitively. Only your option is normalized; the claim is taken verbatim.

The same normalization runs on the minting side, so the string a human's agent passes to aon token get and the audience you write in your source agree as long as they point at the same host. Write the bare hostname you serve on. If your API lives on a subdomain, that subdomain is a separate audience with its own auth.md.

An audience that does not normalize to a hostname — "", "/" — is CONFIG_ERROR, not a mismatch. It is your bug, not the caller's.

What it returnsCopy Anchor Link

A discriminated union on ok. No cast, no in, no optional chaining:

type VerifyAgentTokenResult =
  | { ok: true;  email: string; sub: string; userId?: string; expiresAt: number; jti: string; audience: string }
  | { ok: false; code: VerifyErrorCode; error: string };

The non-throwing contractCopy Anchor Link

Every verification failure returns { ok: false, code, error }. There is no path where an error yields a pass, and no path where a bad key set, a slow endpoint, a forged token, or a misconfigured call throws past the return.

// No try/catch needed around the call itself.
const result = await verifyAgentToken({ token, audience: "notes.com" });

Two things the contract deliberately does not do:

• It does not report the reason a key could not be obtained. Anything a retriever throws is discarded and replaced with a message the SDK wrote. Log inside your own retriever.
• It does not cache verification results. A cached "this token is valid" is how a revoked or rotated token keeps working. Only key sets are cached, and only for an hour.

NextCopy Anchor Link