Developers · @aiidentity/sdk

Verify any AI in one line.

@aiidentity/sdk is the official client for the AI Identity registry. Cryptographically verify Passports, look up the public WHOIS, and authenticate MCP servers — from any JavaScript runtime, with no dependencies.

Install

npm install @aiidentity/sdk
Select to copy

Also works with pnpm add, yarn add, bun add, and deno add npm:@aiidentity/sdk.

30-second hook

Anywhere you receive a Passport from another AI or service:

import { verify } from "@aiidentity/sdk";

const result = await verify(passportToken);

if (result.valid) {
  console.log(`Verified: ${result.operator} (${result.tier})`);
} else {
  console.warn(`Rejected — ${result.reason}`);
}
Select to copy
Zero dependencies

7 KB ESM, 8 KB CJS. Tree-shakeable.

Runs anywhere

Node 18+, browsers, Cloudflare Workers, Deno, Bun, Vercel Edge.

Typed surface

Full TypeScript types. v1.x guarantees no breaking changes.

What you'd actually do with it

Five real integrations, in order from simplest to most ambitious.

Scenario 1

Verify an inbound message from another AI

For: bot platforms, chat apps, agent orchestrators.

Some other AI just sent your bot a message claiming to be Acme Bank Assistant. Are they?

import { verify } from "@aiidentity/sdk";

app.message(async ({ message }) => {
  const passport = message.headers?.["x-aii-passport"];
  if (!passport) return; // human, ignore

  const result = await verify(passport);
  if (!result.valid) {
    console.warn(`Rejected AI message — ${result.reason}`);
    return;
  }

  console.log(`Verified: ${result.operator} (${result.tier})`);
  // ... handle the message ...
});
Select to copy

Outcome. One call, three guarantees: signature is real, identity is in the registry, and the record is currently active. You decide policy from there.

Scenario 2

Prove your AI to other AIs (and websites)

For: AI products that talk to the open web.

Your customer-facing chatbot needs to prove who it is on every outgoing response.

// 1. Mint a Passport once (e.g. at deploy time, or on a daily cron).
//    Requires an API key with passport:issue scope; get one in your dashboard.
const res = await fetch("https://aiidentity.org/api/v1/issue", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.AII_API_KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({ identity: "aii_YOUR_ID", ttl_days: 365 }),
});
const { token } = await res.json();
process.env.AII_PASSPORT = token; // store somewhere your edge can read it

// 2. Attach it to every outgoing response.
app.use((req, res, next) => {
  res.setHeader("X-AII-Passport", process.env.AII_PASSPORT);
  next();
});
Select to copy

Outcome. Now any service on the open web that receives a response from your chatbot can call verify(token) and confirm it's really your AI. A first-class issuePassport() SDK method is on the v1.1 roadmap; the HTTP call above is the canonical path today.

Scenario 3

Identify which AIs are scraping your site

For: publishers, paywalls, anti-bot vendors, search engines.

An AI scraper just hit your site. Is it ChatGPT? A startup's indexer? A spam farm?

import { whois } from "@aiidentity/sdk";

app.use(async (req, res, next) => {
  const aiiId = parseAiiFromUserAgent(req.headers["user-agent"]);
  if (!aiiId) return next();

  const record = await whois(aiiId);
  if (!record) return res.status(403).send("Unverified AI");

  console.log(`AI scraper: ${record.display_name} by ${record.operator_display}`);
  console.log(`Tier: ${record.tier} · capabilities: ${record.capabilities.join(", ")}`);

  // Make policy decisions: allow ChatGPT to crawl the article body, block
  // unverified scrapers, charge by tier, etc.
  next();
});
Select to copy

Outcome. You stop building "is this AI legitimate?" classifiers and start querying the registry. Real WHOIS records, real surfaces, real tiers.

Scenario 4

Verify an MCP server before connecting to it

For: MCP clients (Claude Desktop, Cursor, agent frameworks).

A user wants to add an MCP server to your client. You don't want them connecting to a malicious one.

import { verifyMcpIdentity } from "@aiidentity/sdk";

const result = await verifyMcpIdentity("https://your-mcp.example.com", {
  minTier: "business_verified",
});

if (!result.ok) {
  throw new Error(`Refusing to connect to unverified MCP: ${result.reason}`);
}

console.log(`Connecting to ${result.operator_display} — tier: ${result.tier}`);
console.log(`Allowed surfaces: ${result.surfaces.join(", ")}`);
Select to copy

Outcome. The SDK fetches /.well-known/ai-identity.json, validates the registry, confirms the host is a verified surface, and applies your minimum-tier policy. The whole agent-to-agent handshake from /spec/mcp-identity, in three lines.

Scenario 5

Use a white-label registry

For: customers of a white-label AI Identity reseller.

You're using a reseller (Acme Verify) instead of the public aiidentity.org registry.

import { AIIdentityClient } from "@aiidentity/sdk";

const acme = new AIIdentityClient({
  baseUrl: "https://verify.acmeverify.com",
});

const result = await acme.verify({ passport: token });
// Same SDK, same types, same code — just a different domain.
Select to copy

Outcome. Same SDK, same TypeScript types, no fork. Switching from a reseller to the public registry is a one-line change. See /whitelabel.

API reference

The full v1 surface. Everything else in the package is internal and may change.

verify(passportOrIdentity)

Cryptographically verify a Passport JWT, or look up an identity by ID.

import { verify } from "@aiidentity/sdk";

const r = await verify("eyJhbGciOiJFZERTQSI..."); // Passport JWT
// or
const r = await verify("aii_5q9k_abcd1234"); // identity ID

if (r.valid) {
  r.identity      // "aii_..."
  r.tier          // "issued" | "identity_verified" | "creator_verified" | "business_verified"
  r.operator      // "Acme Bank PLC"
  r.status        // "active" | "suspended" | "revoked"
  r.registry_url  // "https://aiidentity.org/p/aii_..."
}
Select to copy

whois(idOrSlug)

Public registry lookup. Returns null if not found (does not throw on 404).

import { whois } from "@aiidentity/sdk";

const record = await whois("aii_5q9k_abcd1234");
if (record) {
  record.display_name      // "Acme Bank Assistant"
  record.operator_display  // "Acme Bank PLC"
  record.surfaces          // ["https://chat.acmebank.example", "wa://+44..."]
  record.capabilities      // ["account-summary", "transfer-initiation"]
}
Select to copy

new AIIdentityClient(options)

Reusable client. Use when you need an API key, a custom base URL, or a shared timeout/UA across many calls.

import { AIIdentityClient } from "@aiidentity/sdk";

const ai = new AIIdentityClient({
  apiKey:    process.env.AII_API_KEY,        // optional
  baseUrl:   "https://aiidentity.org",       // override for white-label
  timeoutMs: 5_000,
  userAgent: "my-app/1.2.3",
});

await ai.verify({ passport: token });
await ai.verify({ identity: "aii_..." });
await ai.whois("aii_...");
await ai.revocations(); // current revocation list — cache aggressively
Select to copy

verifyMcpIdentity(host, options?)

Verify an MCP server's declared AI Identity. Implements the /spec/mcp-identity handshake.

import { verifyMcpIdentity } from "@aiidentity/sdk";

const r = await verifyMcpIdentity("https://my-mcp.example.com", {
  minTier:           "business_verified",      // optional, default: "issued"
  trustedRegistries: ["https://aiidentity.org"], // optional
  timeoutMs:         5_000,                    // optional
});

if (r.ok) {
  r.identity_id, r.tier, r.operator_display, r.surfaces
} else {
  r.reason   // "no_well_known" | "untrusted_registry" | "host_not_a_verified_surface"
             // | "tier_below_policy" | "identity_not_active" | ...
}
Select to copy

AIIdentityError

Thrown by the client on network or HTTP failures (verify, whois, etc.). The standalone helpers swallow 404 for whois only.

import { AIIdentityClient, AIIdentityError } from "@aiidentity/sdk";

try {
  await new AIIdentityClient().verify({ passport: token });
} catch (e) {
  if (e instanceof AIIdentityError) {
    console.error(`[${e.status}] ${e.code}`);
  } else {
    throw e;
  }
}
Select to copy

Stability promise

  • v1.x is stable. verify, whois, AIIdentityClient, verifyMcpIdentity, and AIIdentityError will not break in any 1.x release.
  • Semver, strictly.Patches fix bugs. Minors add features. Majors break things — and we don't do them lightly.
  • No telemetry. The SDK does not phone home, log usage, or include analytics. Every call you see in your network panel is a call you asked for.
  • Zero dependencies. The SDK has no production dependencies. The only network calls go to the registry you configured.

Where next

  • REST API spec — the underlying HTTP endpoints (the SDK is a thin client over these).
  • MCP Identity spec — the standard verifyMcpIdentity implements.
  • Embed badge — for client-side uses where shipping JS is the simpler path.
  • Pricing — the SDK is free; volume calls to the registry have a pricing tier.

SDK source: MIT licensed. Spec: CC-BY 4.0.