@agents-space/verify

Relying Party SDK for agentids.space — verify ID Tokens issued by the IdP and reject revoked keys in real time.

Install

pnpm add @agents-space/verify

Node 22+.

Quick start (Fastify)

import Fastify from "fastify";
import { agentids } from "@agents-space/verify";

const verifier = agentids({
  issuer: "https://agentids.space",
  audience: "rp.example.com",
});
verifier.subscribeRevocations();          // optional but recommended

const app = Fastify();

app.get("/api/me", { preHandler: verifier.fastify }, async (req) => {
  return { agent: req.agent };
});

await app.listen({ port: 5050 });

Quick start (Express)

import express from "express";
import { agentids } from "@agents-space/verify";

const verifier = agentids({ issuer: "...", audience: "..." });

const app = express();
app.post("/api/comment", verifier.express, (req, res) => {
  res.json({ by: req.agent.agentId });
});

What you get on req.agent

{
  agentId: string;
  ownerId: string;
  ownerEmail?: string;
  model: { name: string; vendor: string };
  keyId: string;
  jkt: string;
  issuedAt: Date;
  expiresAt: Date;
  raw: IdTokenClaims;          // all original claims
}

Bare verify (no framework)

const claims = await verifier.verify({
  authorization: req.headers.authorization,
  dpop: req.headers.dpop,
  method: req.method,
  url: `https://${req.headers.host}${req.url}`,
});

Throws VerifyError (with a .code) on any failure.

Configuration

agentids({
  issuer: "https://agentids.space",   // required
  audience: "rp.example.com",         // required — your RP id
  publicBaseUrl: "https://api.foo",   // optional, override URL inference behind proxies
  replayCache: customReplayCache,     // optional, swap in Redis/etc.
});

Real-time revocation

const sub = verifier.subscribeRevocations({
  since: lastSeenRevocationId,        // resume after restart
  onEvent: (rev) => persist(rev.id),
  onError: (e) => console.error(e),
});
await sub.ready;                      // initial DB replay complete

After sub.ready, verify() rejects any token whose key_id is revoked.

See also

• Full RP integration guide
• Spec