@vouchid/sdk

The official JavaScript SDK for VouchID — identity infrastructure for AI agents.

Register agents, manage tokens with automatic refresh, verify identities, and check permissions. Built for Node.js 18+, zero dependencies.

npm install @vouchid/sdk

Quick Start

import { AgentID } from "@vouchid/sdk";

const agentid = new AgentID({
  apiUrl: process.env.AGENTID_API_URL,
  apiKey: process.env.AGENTID_API_KEY,
});

// Register a new agent
const agent = await agentid.register({
  name: "my-data-bot",
  capabilities: ["read:data", "write:reports"],
  model: "gpt-4o",
});

// Get a token — auto-refreshes when expiry is near
const token = await agent.getToken();

// Attach it to any outgoing MCP request
params._agentid_token = token;

Concepts

AgentID is the entry point. Instantiate it once with your API key and reuse it across your application.

AgentClient is returned by register() and loadAgent(). It represents a single registered agent and manages its token lifecycle — including automatic refresh when the token is within 7 days of expiry.

Persisting agents — after registering, call agent.toJSON() and store the result. On the next startup, pass it to agentid.loadAgent() instead of re-registering.

API Reference

new AgentID(options)

| Option | Default | Description | | ---------------------- | ------------------------- | ---------------------------------------------------------------- | | apiKey | — | Required. Your org API key. | | apiUrl | https://api.vouchid.dev | Override for local dev or staging. | | refreshThresholdDays | 7 | Refresh token if fewer than this many days remain. | | timeoutMs | 10000 | Per-request timeout in ms. | | maxRetries | 3 | Retry attempts on 429/5xx and network errors. | | logger | console | Custom logger with .info/.warn/.error. Pass null to silence. |

agentid.register({ name, capabilities, model? })

Creates a new agent and returns an AgentClient. Call this once on first run, then persist the result with agent.toJSON().

Capability strings follow the format scope:action — e.g. read:data, write:payments, execute:queries.

agentid.loadAgent({ agentId, token, expiresAt, capabilities, trustLevel })

Restores an AgentClient from a previously serialised state. Makes no network call. Use this on every startup after the first registration.

agentid.verify(token, requiredCapabilities?)

Verifies a raw token string. Public endpoint — no API key required. Pass an optional array of capability strings to assert the agent has them.

agentid.checkPermission(agentId, capability, context?)

Runtime permission check. Designed to run in under 5ms. Pass context (e.g. { amount: 250 }) for policy-aware evaluation.

agentid.getReputation(agentId)

Returns the agent's current trust score, total verifications, and success rate.

agentid.revoke(agentId)

Immediately revokes an agent's token.

agent.getToken()

Returns the current token string, refreshing it first if it is within refreshThresholdDays of expiry. Concurrent calls are coalesced — only one refresh request is made even if many calls arrive simultaneously.

agent.toJSON()

Serialises the agent to a plain object safe for database storage, environment variables, or files.

const state = agent.toJSON();
// { agentId, token, expiresAt, capabilities, trustLevel }

// Restore later:
const agent = agentid.loadAgent(state);

Error Handling

All methods throw AgentIDError on failure. Catch it specifically to avoid swallowing unrelated errors.

import { AgentID, AgentIDError } from "@vouchid/sdk";

try {
  const agent = await agentid.register({ ... });
} catch (err) {
  if (err instanceof AgentIDError) {
    console.error(err.code);    // machine-readable code
    console.error(err.message); // human-readable description
  }
}

| Code | Cause | | ---------------- | -------------------------------------------------------------------- | | INVALID_CONFIG | Missing or invalid constructor options. | | INVALID_INPUT | Bad method arguments (e.g. missing name, invalid capability format). | | API_ERROR | Backend returned an error status. Check err.statusCode. | | NETWORK_ERROR | All retry attempts exhausted. Backend unreachable. | | PARSE_ERROR | Unexpected response format from the backend. |

Using with MCP

Attach the token to every outgoing MCP tool call via _agentid_token in the request params. The @vouchid/mcp middleware on the receiving server will verify it automatically.

const token = await agent.getToken();

await mcpClient.callTool({
  name: "read_file",
  arguments: {
    path: "/data/report.csv",
    _agentid_token: token,
  },
});

For server-side verification, see @vouchid/mcp.

Requirements

• Node.js 18 or later
• ESM ("type": "module") or a bundler that handles ESM

License

MIT