Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.imarobot.ai/llms.txt

Use this file to discover all available pages before exploring further.

Available on Developer plan and above. Upgrade at app.imarobot.ai.

​
Install

npm install imarobot-agent

​
Quick start

import { ImaRobotAgent } from 'imarobot-agent';
import fs from 'fs';

const client = new ImaRobotAgent({
  apiKey: 'sk_live_YOUR_KEY',
  privateKeyPem: fs.readFileSync('./keys/private.pem', 'utf8'),
});

// Register an agent
const agent = await client.registerAgent({
  name: 'PortfolioBot',
  issuerDomain: 'apexwealth.com',
  scopes: ['read:portfolio', 'read:transactions'],
});

// Issue a token
const { token } = await client.issueToken(agent.agentId);

// Use token to call a receiver API...

// Revoke when done
await client.revokeAgent(agent.agentId, { reason: 'Session complete' });

​
Generate a key pair

The SDK includes a CLI helper so you don’t need to touch OpenSSL: 
npx imarobot-agent generate-keys --output ./keys
# Writes: ./keys/private.pem and ./keys/public.pem
  • Private key — keep secret. Used by your agent process to sign requests.
  • Public key — upload to ImaRobot during registerAgent(). Safe to commit.

​
API

​
new ImaRobotAgent(options)

OptionTypeRequiredDescription
apiKeystring✓Your sk_live_ or sk_test_ API key
privateKeyPemstring✓RS256 private key PEM string
baseUrlstring—Default: https://api.imarobot.ai

​
client.registerAgent(options)

const agent = await client.registerAgent({
  name: string,           // Required — human-readable name
  issuerDomain: string,   // Required — your domain (e.g. 'apexwealth.com')
  scopes: string[],       // Required — what this agent can do
  description?: string,   // Optional
  expiryDays?: number,    // Default: 1. Max: 90 (Enterprise: 365)
})
Returns: { agentId, name, status, expiresAt }

​
client.issueToken(agentId)

const { token, expiresAt } = await client.issueToken(agentId: string)
Issues a fresh token for an existing agent. The token embeds all scopes and expiry from registration.

​
client.revokeAgent(agentId, options?)

await client.revokeAgent(agentId: string, { reason?: string })
Revokes immediately. Subsequent verifications return TOKEN_REVOKED.

​
client.rotateAgent(agentId, options?)

Revoke + re-register in one call. Returns the new agent. 
const newAgent = await client.rotateAgent(agentId: string, {
  expiryDays?: number,
  scopes?: string[], // Optional — update scopes on rotation
})

​
client.listAgents(options?)

const { agents } = await client.listAgents({
  status?: 'active' | 'revoked' | 'expired',
  limit?: number,   // Default: 50
  cursor?: string,
})

​
TypeScript

import { ImaRobotAgent, Agent, VerifyResult } from 'imarobot-agent';