Skip to main content

​
Install

npm install imarobot-verify

​
Quick start

import { createVerifier } from 'imarobot-verify';

const verifier = createVerifier({
  publishableKey: 'pk_live_YOUR_KEY', // From app.imarobot.ai/settings/api-keys
});

const result = await verifier.verify(token);
// { valid: true, agentId, issuer, scopes, expiresAt }
// { valid: false, error: 'TOKEN_REVOKED' | 'TOKEN_EXPIRED' | 'TOKEN_INVALID' }
Get your publishable key from app.imarobot.ai/settings/api-keys.

​
API

​
createVerifier(options)

OptionTypeDefaultDescription
publishableKeystringrequiredYour pk_live_ or pk_test_ key
mode'online' | 'offline''online'Online checks revocation; offline is local-only
cacheTTLnumber300Seconds to cache public keys
timeoutnumber3000Ms before falling back to offline
Returns an object with verify(), middleware(), and warmCache().

​
verifier.verify(token)

const result = await verifier.verify(token: string): Promise<VerifyResult>
Success response: 
{
  "valid": true,
  "agentId": "agt_abc123",
  "name": "PortfolioBot",
  "issuer": "imarobot.ai",
  "scopes": ["read:portfolio"],
  "expiresAt": "2026-03-27T18:00:00.000Z"
}
Failure response: 
{
  "valid": false,
  "error": "TOKEN_REVOKED"
}
Error values: TOKEN_REVOKED | TOKEN_EXPIRED | TOKEN_INVALID

​
verifier.middleware()

Express middleware. Attaches req.agent on success, returns 401 on failure. 
app.use('/api/protected', verifier.middleware());

app.get('/api/protected/data', (req, res) => {
  const { agentId, scopes } = req.agent;
  
  if (!scopes.includes('read:data')) {
    return res.status(403).json({ error: 'FORBIDDEN' });
  }
  
  res.json({ message: 'ok' });
});

​
verifier.warmCache(domains)

Pre-fetch and cache public keys for known issuer domains. 
await verifier.warmCache(['apexwealth.com', 'yourpartner.com']);
Call this at startup to eliminate cold-start latency on the first verification.

​
Offline mode

See Offline mode for details on when to use local-only validation.

​
TypeScript

The SDK ships with full TypeScript types. No @types package needed. 
import { createVerifier, VerifyResult } from 'imarobot-verify';

​
Source

Open source — github.com/humansandrobots/imarobot-verify