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
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}`);
}7 KB ESM, 8 KB CJS. Tree-shakeable.
Node 18+, browsers, Cloudflare Workers, Deno, Bun, Vercel Edge.
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.
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 ...
});Outcome. One call, three guarantees: signature is real, identity is in the registry, and the record is currently active. You decide policy from there.
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();
});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.
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();
});Outcome. You stop building "is this AI legitimate?" classifiers and start querying the registry. Real WHOIS records, real surfaces, real tiers.
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(", ")}`);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.
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.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_..."
}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"]
}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 aggressivelyverifyMcpIdentity(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" | ...
}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;
}
}Stability promise
- v1.x is stable.
verify,whois,AIIdentityClient,verifyMcpIdentity, andAIIdentityErrorwill 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
verifyMcpIdentityimplements. - 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.