How to Add Verifiable Identity to Your AI Agent in 5 Minutes

#ai #typescript #identity #tutorial

As AI agents start calling APIs, signing contracts, and talking to each other, one question keeps coming up: how do you know which agent you're dealing with?

AgentPass gives every agent a cryptographic passport — a verifiable identity that other agents and services can check in milliseconds. Here's how to set it up.

Prerequisites

Node.js 18+
TypeScript project
5 minutes

Step 1: Install the SDK

npm install @agentpass/sdk

The SDK gives you AgentPassClient for interacting with the AgentPass API, plus middleware helpers for verifying incoming agent requests.

Step 2: Generate a Key Pair and Register a Passport

Every agent passport is backed by an Ed25519 key pair. You generate keys locally and register the public key with AgentPass:

import { webcrypto } from 'node:crypto';

// Generate an Ed25519 key pair
const keyPair = await webcrypto.subtle.generateKey(
  'Ed25519',
  true, // extractable
  ['sign', 'verify']
);

// Export the public key as base64
const pubRaw = await webcrypto.subtle.exportKey('raw', keyPair.publicKey);
const publicKeyB64 = Buffer.from(pubRaw).toString('base64');

// Register with the AgentPass API
const res = await fetch('https://api.agentpass.space/passports', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    public_key: publicKeyB64,
    name: 'my-trading-agent',
    description: 'Executes trades on DEX protocols',
  }),
});

const passport = await res.json();
console.log(passport.id); // => "ap_a3f8b2c1d4e5"

That's it — your agent now has a globally unique passport ID (ap_xxxxxxxxxxxx) tied to its cryptographic key.

Tip: Store the private key securely. The public key is on the server; the private key never leaves your agent.

Step 3: Sign Requests (Prove You Are You)

When your agent calls another service, it signs a challenge with its private key:

async function signChallenge(
  privateKey: CryptoKey,
  challenge: string
): Promise<string> {
  const sig = await webcrypto.subtle.sign(
    'Ed25519',
    privateKey,
    new TextEncoder().encode(challenge)
  );
  return Buffer.from(sig).toString('base64');
}

// Example: authenticate to a partner service
const challenge = 'random-challenge-from-server';
const signature = await signChallenge(keyPair.privateKey, challenge);

await fetch('https://partner-api.example.com/data', {
  headers: {
    'X-AgentPass-ID': passport.id,
    'X-AgentPass-Signature': signature,
  },
});

The receiving service can now verify this signature against AgentPass — no shared secrets, no API keys to rotate.

Step 4: Verify Another Agent's Identity

On the receiving side, use the SDK to verify incoming requests:

import {
  AgentPassClient,
  createVerificationMiddleware,
} from '@agentpass/sdk';

// Option A: Direct verification
const client = new AgentPassClient({
  apiUrl: 'https://api.agentpass.space',
});

const result = await client.verifyPassport(
  'ap_a3f8b2c1d4e5', // passport ID from header
  challenge,          // the challenge you issued
  signature           // the signature from header
);

console.log(result.valid);       // true
console.log(result.trust_score); // 0.85
console.log(result.status);      // "active"

// Option B: Drop-in middleware
const verify = createVerificationMiddleware({
  apiUrl: 'https://api.agentpass.space',
});

// Works with any framework — Express, Hono, Fastify
app.use(async (req, res, next) => {
  const agent = await verify(req.headers);
  if (!agent || !agent.valid) {
    return res.status(401).json({ error: 'Invalid agent identity' });
  }
  req.agent = agent; // { passport_id, trust_score, status }
  next();
});

The trust_score (0-1) reflects the passport's history — verified credentials, uptime, abuse reports. Use it for graduated access control.

Step 5: Look Up Any Agent

Need to check who you're about to interact with?

const info = await client.getPassport('ap_a3f8b2c1d4e5');

console.log(info.name);        // "my-trading-agent"
console.log(info.trust_score); // 0.85
console.log(info.status);      // "active"
console.log(info.created_at);  // "2026-03-10T..."

What You Get

Feature	How
Unique agent identity	`ap_xxxxxxxxxxxx` passport ID
Cryptographic proof	Ed25519 sign/verify
Trust scoring	Reputation from 0 to 1
Zero shared secrets	Public key crypto, not API keys
Agent-to-agent messaging	Built-in via SDK
Abuse reporting	`client.reportAbuse()`