Quick Start

Get up and running with Agent OTP in minutes. This guide will walk you through installation, setup, and requesting your first OTP.

Prerequisites

• Node.js 18+ or Bun 1.0+
• An Agent OTP API key (self-hosted or from agentotp.com)
• An AI agent or application that needs OTP verification

Step 1: Install the SDK

Install the Agent OTP SDK in your project:

npm install @orrisai/agent-otp-sdk

bun add @orrisai/agent-otp-sdk

pnpm add @orrisai/agent-otp-sdk

Step 2: Initialize the Client

Create an Agent OTP client with your API key. We recommend using environment variables:

// lib/otp.ts
import { AgentOTPClient } from '@orrisai/agent-otp-sdk';

export const otpClient = new AgentOTPClient({
  apiKey: process.env.AGENT_OTP_API_KEY!,
  // For self-hosted deployments:
  // baseUrl: 'https://otp.your-domain.com',
});

Step 3: Generate Encryption Keys

Agent OTP uses end-to-end encryption. Generate a key pair for your agent and store the private key securely:

import {
  generateKeyPair,
  exportPublicKey,
  exportPrivateKey,
} from '@orrisai/agent-otp-sdk';

// Generate keys (do this once, store securely)
const { publicKey, privateKey } = await generateKeyPair();

// Export for storage
const publicKeyBase64 = await exportPublicKey(publicKey);
const privateKeyBase64 = await exportPrivateKey(privateKey);

// Store privateKeyBase64 securely (e.g., environment variable, secrets manager)
console.log('Public Key:', publicKeyBase64);
console.log('Private Key:', privateKeyBase64); // Keep this secret!

Step 4: Request an OTP

Now you can request OTPs for verification. Here's a complete example:

import { otpClient } from './lib/otp';
import { importPrivateKey, exportPublicKey } from '@orrisai/agent-otp-sdk';

async function signUpForService(email: string) {
  // Load your keys (in production, load from secure storage)
  const privateKey = await importPrivateKey(process.env.AGENT_PRIVATE_KEY!);
  const publicKeyBase64 = process.env.AGENT_PUBLIC_KEY!;

  // Request an OTP
  const request = await otpClient.requestOTP({
    reason: 'Sign up verification for Acme Inc',
    expectedSender: 'Acme',
    filter: {
      sources: ['email'],
      senderPattern: '*@acme.com',
    },
    publicKey: publicKeyBase64,
    waitForOTP: true,
    timeout: 120000, // Wait up to 2 minutes
    onPendingApproval: (info) => {
      console.log('Please approve at:', info.approvalUrl);
    },
  });

  // Check the result
  if (request.status === 'otp_received') {
    // Consume and decrypt the OTP
    const { code, metadata } = await otpClient.consumeOTP(request.id, privateKey);

    console.log('OTP code:', code);
    console.log('From:', metadata?.sender);

    // Use the code to complete sign up
    return { success: true, code };
  } else if (request.status === 'denied') {
    console.log('User denied the request');
    return { success: false, error: 'denied' };
  } else if (request.status === 'expired') {
    console.log('Request expired');
    return { success: false, error: 'expired' };
  }

  return { success: false, error: request.status };
}

Step 5: Set Up OTP Capture (Optional)

To capture OTPs, you need to set up one of the capture methods:

Understanding Request Status

OTP requests go through several states:

Next Steps

• Learn how Agent OTP works in depth
• Understand the encryption model
• Explore the full SDK reference
• Self-host Agent OTP