Getting Started

Get up and running with Agent-Pass in under 5 minutes. This guide covers installation, basic usage, and your first authentication flow.

⚡ 5-minute setup

Complete authentication flow in just a few steps

Prerequisites

Required

Node.js 18+ or Bun
TypeScript 5.0+
Basic understanding of cryptography

Recommended

Familiarity with W3C DIDs
Understanding of JWT/JWS
Express.js knowledge (for middleware)

Installation

Install with npmbash

# Install the core package
npm install agent-pass

# For TypeScript projects (recommended)
npm install --save-dev @types/node

# Optional: Express.js middleware
npm install agent-pass-express

Quick Start Example

Let's create your first AI agent and authenticate it step by step.

Initialize Agent-Pass

Initialize the SDKtypescript

import { AgentPass } from 'agent-pass';

// Initialize with security configuration
const agentPass = new AgentPass({
  keyType: 'Ed25519',           // Cryptographic algorithm
  didMethod: 'did:key',         // DID method
  security: {
    challengeTimeout: 300,      // 5 minutes
    nonceLength: 32             // Secure nonce length
  }
});

console.log('✅ Agent-Pass initialized');

Create an AI Agent Identity

Create Agent DIDtypescript

// Create a new AI agent with capabilities
const agent = await agentPass.createAgent({
  name: 'DataProcessingAgent',
  version: '1.0.0',
  capabilities: [
    'data:read',
    'data:process', 
    'logs:write'
  ]
});

console.log('Agent DID:', agent.did);
// Output: did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

console.log('Public Key:', agent.publicKey);
console.log('✅ Agent identity created');

Issue Capability Credentials

Issue Credentialstypescript

// Controller issues capability credential
const credential = await agentPass.issueCredential(agent, {
  issuer: 'did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH',
  scopes: [
    'read:user-data',
    'write:processing-logs',
    'access:ml-models'
  ],
  constraints: {
    timeLimit: '24h',               // Valid for 24 hours
    ipRange: '192.168.1.0/24',      // Network restriction
    rateLimits: {
      requestsPerMinute: 100,
      dataProcessingMB: 500
    }
  },
  metadata: {
    purpose: 'Data processing and analysis',
    compliance: ['GDPR', 'SOC2']
  }
});

console.log('✅ Credential issued');
console.log('Credential ID:', credential.id);

Authenticate and Authorize

Dual Signature Authenticationtypescript

// Create a request that needs authorization
const request = {
  action: 'processUserData',
  resource: '/api/users/analytics',
  timestamp: Date.now(),
  nonce: crypto.randomUUID()
};

// Agent signs the request
const agentSignature = await agent.sign(request);

// Verify credential and signature
const verification = await agentPass.verifyCredential(credential, {
  signature: agentSignature,
  request: request,
  currentTime: Date.now()
});

if (verification.valid) {
  console.log('✅ Authentication successful!');
  console.log('Granted scopes:', verification.grantedScopes);
  console.log('Valid until:', verification.expiresAt);
  
  // Proceed with authorized action
  await performDataProcessing(request);
} else {
  console.error('❌ Authentication failed:', verification.reason);
}

Complete Working Example

Here's a complete example you can run immediately:

complete-example.tstypescript

import { AgentPass } from 'agent-pass';
import crypto from 'crypto';

async function main() {
  try {
    // 1. Initialize Agent-Pass
    const agentPass = new AgentPass({
      keyType: 'Ed25519',
      didMethod: 'did:key',
      security: {
        challengeTimeout: 300,
        nonceLength: 32
      }
    });

    // 2. Create AI agent
    const agent = await agentPass.createAgent({
      name: 'ExampleAgent',
      version: '1.0.0',
      capabilities: ['data:read', 'data:process']
    });

    console.log('🤖 Agent created:', agent.did);

    // 3. Issue credential
    const credential = await agentPass.issueCredential(agent, {
      issuer: 'did:key:controller-did-here',
      scopes: ['read:data', 'process:analytics'],
      constraints: {
        timeLimit: '1h',
        ipRange: '0.0.0.0/0' // Allow all IPs for demo
      }
    });

    console.log('🎫 Credential issued:', credential.id);

    // 4. Create and sign request
    const request = {
      action: 'readData',
      resource: '/api/data',
      timestamp: Date.now(),
      nonce: crypto.randomUUID()
    };

    const signature = await agent.sign(request);
    console.log('✍️ Request signed');

    // 5. Verify authentication
    const verification = await agentPass.verifyCredential(credential, {
      signature,
      request,
      currentTime: Date.now()
    });

    if (verification.valid) {
      console.log('✅ Authentication successful!');
      console.log('📋 Granted scopes:', verification.grantedScopes);
      console.log('⏰ Valid until:', new Date(verification.expiresAt));
    } else {
      console.error('❌ Authentication failed:', verification.reason);
    }

  } catch (error) {
    console.error('💥 Error:', error.message);
  }
}

// Run the example
main().catch(console.error);

Common Issues & Solutions

TypeScript errors: Make sure you have @types/node installed and your tsconfig.json includes ES2020+ target for crypto support.

Crypto module not found: Agent-Pass requires Node.js crypto module. In browser environments, use a crypto polyfill.

Signature verification failed: Ensure timestamps are recent (within challengeTimeout) and nonces are unique per request.

Next Steps

Express.js Integration

Learn how to integrate Agent-Pass with Express.js middleware

Architecture Deep Dive

Understand the technical architecture and design decisions

More Examples API Reference