vexis-sdk

TypeScript SDK for Vexis — cryptographic identity and trust infrastructure for AI agents.

What is Vexis?

Vexis provides cryptographic passports for AI agents. Agents get signed credentials (short-lived JWTs), receiving systems verify them without needing a Vexis account, and every interaction feeds a trust graph that scores agent reputation over time (0-100).

The trust graph uses anomaly detection to flag suspicious behavior in real time and builds persistent cross-organizational reputation that follows agents across systems.

The SDK gives you 6 core functions: issue, verify, attest, revoke, lookup, and trust.

Prerequisites

• Node.js 18+
• TypeScript 5+ (recommended)

Installation

npm install vexis-sdk

Quick Start

import { Vexis } from 'vexis-sdk';

const vexis = new Vexis({
  apiKey: 'vr_live_...',       // from the Vexis dashboard
  baseUrl: 'https://your-api-url', // your Vexis API deployment
});

// 1. Issue a passport for an AI agent
const passport = await vexis.issue({
  agentName: 'data-fetcher',
  agentType: 'retrieval',
  capabilities: [
    { name: 'documents:read', scope: '*' },
  ],
});

// 2. Verify the passport (no auth required — call this on the receiving side)
const result = await vexis.verify({ token: passport.token });
if (result.valid) {
  console.log(`Trust score: ${result.trustScore}`);
}

// 3. Record the outcome of an interaction
await vexis.attest({
  passportId: passport.id,
  action: 'documents:read',
  targetSystem: 'internal-docs',
  outcome: 'success',
});

// 4. Query trust over time
const trust = await vexis.trust({
  orgId: passport.orgId,
  agentName: 'data-fetcher',
  agentType: 'retrieval',
});
console.log(`Overall trust: ${trust.trustScore}`);

Functions

issue() — Mint a new passport

const passport = await vexis.issue({
  agentName: 'data-fetcher',
  agentType: 'retrieval',
  capabilities: [
    { name: 'documents:read', scope: '*' },
    { name: 'api:call', scope: 'external' },
  ],
  ttl: 3600,                    // optional, default 1hr, max 24hr
  boundTo: 'service-x',         // optional, audience binding
  metadata: { env: 'prod' },    // optional, key-value pairs
});
// passport.id, passport.token, passport.expiresAt

verify() — Check a passport token

Does not require authentication — any system can verify a passport.

const result = await vexis.verify({
  token: passport.token,
  requiredCapabilities: ['documents:read'], // optional
  boundTo: 'service-x',                     // optional
});

if (result.valid) {
  console.log(result.trustScore);    // 0-100
  console.log(result.trustFactors);  // { successRate, maturity, recentFailureRate }
  console.log(result.capabilities);  // granted capabilities
} else {
  console.log(result.reason);        // 'expired' | 'revoked' | 'invalid_signature' | ...
  console.log(result.detail);        // human-readable explanation
}

attest() — Record an interaction outcome

const attestation = await vexis.attest({
  passportId: passport.id,
  action: 'documents:read',
  targetSystem: 'internal-docs',
  outcome: 'success',             // success | failure | partial | denied
  durationMs: 1240,               // optional
});
// attestation.trustScoreImpact, attestation.riskSignals

revoke() — Revoke a passport

await vexis.revoke(passport.id, 'compromised');

// Or bulk revoke by agent type
await vexis.bulkRevoke('retrieval', 'key rotation');

lookup() — Get passport details with history

const details = await vexis.lookup(passport.id, {
  limit: 10,   // attestation pagination
  offset: 0,
  since: 1711468800, // unix timestamp
});
// details.passport, details.trustScore, details.attestations, details.verificationHistory

trust() — Query trust scores

// Agent trust
const agent = await vexis.trust({
  orgId: 'org_...',
  agentName: 'data-fetcher',
  agentType: 'retrieval',
});
// agent.trustScore, agent.trustFactors, agent.stats

// Org trust
const org = await vexis.trust({ orgId: 'org_...' });

// Cross-org relationship trust
const rel = await vexis.trust({
  orgId: 'org_...',
  targetOrgId: 'org_other',
});

Error Handling

import { Vexis, VexisApiError } from 'vexis-sdk';

try {
  await vexis.issue({ ... });
} catch (err) {
  if (err instanceof VexisApiError) {
    console.log(err.code);       // 'INVALID_INPUT', 'RATE_LIMITED', 'INVALID_API_KEY', etc.
    console.log(err.message);    // human-readable message with hints
    console.log(err.httpStatus); // HTTP status code
    console.log(err.details);    // optional validation details
  }
}

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your API key from the Vexis dashboard | | baseUrl | string | http://localhost:8787 | API base URL. Set to your deployed Vexis API URL in production. |

Related Packages

| Package | Language | Install | |---------|----------|---------| | vexis-sdk | TypeScript | npm install vexis-sdk | | vexis-cli | CLI | npm install -g vexis-cli | | vexis-mcp | MCP Server | npx vexis-mcp (Claude, Cursor, Windsurf) | | vexis-sdk | Python | pip install vexis-sdk | | vexis-sdk-go | Go | go get github.com/kasenteoh/vexis-sdk-go |

Issues

Found a bug? Open an issue.

License

MIT