Quick Start

Get up and running with Agent OTP in under 5 minutes. This guide will walk you through installation, configuration, and your first permission request.

Prerequisites

• Node.js 18+ or Bun 1.0+
• An Agent OTP account (free tier available)
• An existing AI agent or application

Step 1: Create an account

Sign up for a free account at agentotp.com/signup. You'll get access to:

• 1 agent
• 100 requests per month
• Basic policies
• Email notifications

Step 2: Create an agent

In the dashboard, navigate to Agents and click Create Agent. Give your agent a descriptive name and save. You'll receive an API key that looks like:

ak_live_xxxxxxxxxxxxxxxxxxxx

Step 3: 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 4: Configure the client

Initialize the Agent OTP client with your API key. We recommend using environment variables:

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

export const otp = new AgentOTPClient({
  apiKey: process.env.AGENT_OTP_KEY!,
  // Optional: for self-hosted deployments
  // baseUrl: 'https://your-instance.com',
});

Step 5: Request your first permission

Now you can request permissions for sensitive operations. Here's a complete example:

import { otp } from './lib/otp';

async function sendInvoiceEmail(clientEmail: string, invoiceId: string) {
  // Request permission to send an email
  const permission = await otp.requestPermission({
    action: 'email.send',
    resource: `email:${clientEmail}`,
    scope: {
      max_emails: 1,
      allowed_recipients: [clientEmail],
    },
    context: {
      reason: `Sending invoice #${invoiceId} to client`,
      invoiceId,
    },
    waitForApproval: true, // Blocks until approved/denied
    timeout: 60000, // 60 second timeout
  });

  // Check the result
  if (permission.status === 'approved') {
    console.log('Permission granted! Token:', permission.token);

    // Use the token to send the email
    // The token is scoped to exactly this operation
    await yourEmailService.send({
      to: clientEmail,
      subject: `Invoice #${invoiceId}`,
      // Pass the OTP token for verification
      otpToken: permission.token,
    });

    // Mark the token as used
    await otp.useToken(permission.token, {
      recipient: clientEmail,
      invoiceId,
    });

    return { success: true };
  } else if (permission.status === 'denied') {
    console.log('Permission denied:', permission.reason);
    return { success: false, error: 'Permission denied' };
  } else {
    console.log('Permission timed out');
    return { success: false, error: 'Approval timeout' };
  }
}

Step 6: Configure policies (optional)

By default, all permission requests require human approval. You can configure policies to auto-approve safe operations:

# Auto-approve file reads under 1MB
- name: "Auto-approve small file reads"
  conditions:
    action:
      equals: "file.read"
    scope.max_size:
      less_than: 1048576
  action: auto_approve

# Require approval for any financial operation
- name: "Financial operations"
  conditions:
    action:
      starts_with: "bank."
  action: require_approval
  priority: 100

See the Policies documentation for more details.

Next steps

• Understand permissions and scopes
• Set up Telegram notifications
• Explore the full SDK reference
• Integrate with LangChain