AgentPass Class API

Complete API reference for the AgentPass class, the main interface for all Agent-Pass authentication operations including identity management, credential handling, and verification.

Quick Start

Import Path: The AgentPass class is the main entry point. All other classes are accessible through this unified interface.

Basic Setup

import { AgentPass } from '@agent-pass/core';

// Create instance with default configuration
const agentPass = new AgentPass();

// Or with custom configuration
const agentPass = new AgentPass({
  keyManagementSystem: 'local',
  didMethod: 'key',
  defaultKeyType: 'Ed25519',
  clockSkewTolerance: 300
});

Constructor

constructor(config?: AgentPassConfig)

Creates a new AgentPass instance with optional configuration. Uses sensible defaults if no config provided.

Parameters

config?: {
  keyManagementSystem?: 'local' | 'aws-kms' | 'azure-kv' | 'gcp-kms';
  didMethod?: 'key' | 'web' | 'ion';
  defaultKeyType?: 'Ed25519' | 'Secp256k1';
  clockSkewTolerance?: number;
  challengeExpirationTime?: number;
  maxCredentialAge?: number;
}

Returns

AgentPass

Example

// Default configuration
const agentPass = new AgentPass();

// Custom configuration
const agentPass = new AgentPass({
  clockSkewTolerance: 60, // 1 minute tolerance
  challengeExpirationTime: 600, // 10 minute challenges
  defaultKeyType: 'Ed25519'
});

API Methods

Identity Management

createAgentIdentity(options?: CreateAgentOptions)

Creates a new agent identity with a unique DID and cryptographic key pair.

Parameters

options?: {
  alias?: string;
  keyType?: 'Ed25519' | 'Secp256k1';
}

Returns

Promise<AgentIdentity>

Example

const agent = await agentPass.createAgentIdentity({
  alias: 'email-assistant',
  keyType: 'Ed25519'
});

console.log(agent.did);   // did:key:z6MkhaXg...
console.log(agent.keyId); // z6MkhaXg...

createControllerIdentity(options?: CreateAgentOptions)

Creates a new controller identity for a human user who will delegate authority to agents.

Parameters

options?: {
  alias?: string;
  keyType?: 'Ed25519' | 'Secp256k1';
}

Returns

Promise<ControllerIdentity>

Example

const controller = await agentPass.createControllerIdentity({
  alias: 'human-manager',
  keyType: 'Ed25519'
});

console.log(controller.did);   // did:key:z6MkpTHR...
console.log(controller.keyId); // z6MkpTHR...

getIdentity(did: string)

Retrieves an existing identity by its DID, or null if not found.

Parameters

did: string

Returns

Promise<IIdentifier | null>

Example

const identity = await agentPass.getIdentity(
  'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK'
);

if (identity) {
  console.log('Found identity:', identity.alias);
} else {
  console.log('Identity not found');
}

listIdentities()

Lists all managed identities in the current Agent-Pass instance.

Parameters

(none)

Returns

Promise<IIdentifier[]>

Example

const identities = await agentPass.listIdentities();

identities.forEach(identity => {
  console.log(`${identity.alias}: ${identity.did}`);
});

deleteIdentity(did: string)

Deletes an identity from the key management system. Returns true if successful.

Parameters

did: string

Returns

Promise<boolean>

Example

const deleted = await agentPass.deleteIdentity(
  'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK'
);

if (deleted) {
  console.log('Identity successfully deleted');
}

Error Handling

Agent-Pass methods throw structured errors with specific error codes for different failure scenarios.

Error Handling Example

import { AgentPass, AgentPassErrorCode } from '@agent-pass/core';

try {
  const verification = await agentPass.verifyVerifiablePresentation(
    presentation,
    challenge.challenge,
    challenge.domain
  );
  
  if (!verification.verified) {
    console.error('Verification failed:', verification.error);
    return;
  }
  
  // Process successful verification
  console.log('Success:', verification);
  
} catch (error) {
  if (error.code === AgentPassErrorCode.VERIFICATION_FAILED) {
    console.error('Verification error:', error.message);
  } else if (error.code === AgentPassErrorCode.CREDENTIAL_EXPIRED) {
    console.error('Credential has expired');
  } else {
    console.error('Unexpected error:', error);
  }
}

Common Error Codes

Standard error codes returned by Agent-Pass methods

Identity Errors

• IDENTITY_CREATION_FAILED
• DID_RESOLUTION_FAILED
• KEY_MANAGEMENT_ERROR

Credential Errors

• CREDENTIAL_ISSUANCE_FAILED
• CREDENTIAL_EXPIRED
• CREDENTIAL_REVOKED

Verification Errors

• VERIFICATION_FAILED
• INVALID_SIGNATURE
• INVALID_CHALLENGE

Authorization Errors

• PERMISSION_DENIED
• PRESENTATION_CREATION_FAILED
• CONFIGURATION_ERROR

Next Steps

Types & Interfaces

Complete TypeScript type definitions and interfaces

Working Examples

See the API in action with complete code examples