Permissions

Permissions are the core concept in Agent OTP. A permission grants an AI agent the ability to perform a specific action on a specific resource, with defined constraints.

Anatomy of a Permission

Every permission request consists of four key components:

1Action

What the agent wants to do (e.g., email.send, file.write)

2Resource

The target of the action (e.g., email:user@example.com)

3Scope

Constraints on the permission (e.g., max_emails: 1)

4Context

Additional information for approval decisions (e.g., reason: "Sending invoice")

Action Naming Convention

Actions follow a hierarchical naming pattern: category.operation. This allows for flexible policy matching:

email.send        # Send an email
email.read        # Read emails
email.*           # Any email operation

file.read         # Read a file
file.write        # Write a file
file.delete       # Delete a file

bank.transfer     # Transfer money
bank.balance      # Check balance

api.call          # Make an API call
shell.execute     # Execute a shell command

Resource Identifiers

Resources use a type:identifier format to clearly specify what is being accessed:

email:user@example.com     # A specific email address
file:/path/to/file.txt     # A specific file path
table:users                # A database table
account:checking           # A bank account
api:stripe.com             # An API endpoint
env:production             # An environment

Permission Lifecycle

Request

Agent requests permission via SDK. Request is assigned a unique ID.

Evaluate

Policy engine evaluates the request against configured policies. Determines if auto-approve, require approval, or deny.

Approve

If auto-approved, token is issued immediately. If human approval required, notification is sent and agent waits.

Issue Token

Upon approval, a scoped, ephemeral token is generated and returned to the agent.

Use

Agent uses the token to perform the operation. Token is marked as used (one-time use by default).

Expire

Token expires after use, after TTL, or when manually revoked. All actions are logged in the audit trail.

Permission Statuses

Status	Description
pending	Waiting for human approval
approved	Permission granted, token issued
denied	Permission denied by policy or human
expired	Request or token has expired
used	Token has been consumed

Example Request

const permission = await otp.requestPermission({
  // What action to perform
  action: 'email.send',

  // Target resource
  resource: 'email:client@acme.com',

  // Constraints on the permission
  scope: {
    max_emails: 1,
    subject_pattern: '^Invoice #[0-9]+$',
    attachment_allowed: true,
    max_attachment_size: 5242880, // 5MB
  },

  // Context for approval decision
  context: {
    reason: 'Sending monthly invoice to client',
    invoice_id: 'INV-2024-001',
    triggered_by: 'scheduled_task',
  },

  // How long the token should be valid (seconds)
  ttl: 300, // 5 minutes

  // Wait for approval before returning
  waitForApproval: true,
  timeout: 60000, // 60 second timeout
});