aliaskit

Agent identity infrastructure: give any AI agent a real email inbox, phone number, and virtual debit card. Sign agents up to services, extract verification codes automatically, and subscribe to inbound messages over WebSockets.

Install

npm install aliaskit

The SDK works in Node 18+, Bun, Deno, and modern browsers. Native fetch and Web Crypto API only — no Node-only dependencies.

TypeScript setup

If you are using TypeScript, make sure @types/node is installed (the SDK uses Node.js crypto for card encryption and Buffer for attachments):

npm install -D @types/node

If your tsconfig.json sets "types": [], change it to "types": ["node"] or remove the field entirely.

Environment variables

The SDK reads ALIASKIT_API_KEY and ALIASKIT_CARD_KEY from process.env. If you use a .env file, load it before importing the SDK:

// Option A: Node 20+ built-in .env support
// Run with: node --env-file=.env your-script.js

// Option B: dotenv
import 'dotenv/config'
import { AliasKit } from 'aliaskit'

5-Minute Quickstart

1. Get your API key

Sign up at aliaskit.com and grab an API key from the dashboard. Set it as an environment variable:

export ALIASKIT_API_KEY="ak_live_..."

2. Provision an identity, sign your agent up, retrieve the OTP

import { AliasKit } from 'aliaskit';

const ak = new AliasKit(); // reads ALIASKIT_API_KEY from env

async function signupAgent() {
  // Provision a fresh identity with a real email inbox
  const identity = await ak.identities.create();
  console.log('Acting as:', identity.email); // alex.smith.k4f2@aliaskit.com

  try {
    // ... your agent triggers a signup using identity.email ...

    // Wait for the verification email and extract the OTP
    const code = await ak.emails.waitForCode(identity.id, {
      provider: 'supabase', // or 'clerk', 'auth0', or omit for auto-detect
      timeout: 60_000,
    });
    console.log('Got OTP:', code); // "123456"

    // ... your agent submits the code to complete signup ...
  } finally {
    // Release the identity when the agent is done
    await ak.identities.delete(identity.id);
  }
}

signupAgent();

3. With SMS verification (Pro plan)

const identity = await ak.identities.create({ provisionPhone: true });
console.log('Phone:', identity.phone_number); // +447xxxxxxxxx

// ... your agent triggers an SMS verification ...

const code = await ak.sms.waitForCode(identity.id);
console.log('SMS OTP:', code);

await ak.identities.delete(identity.id);

4. Realtime — react to inbound messages instantly

Treat incoming SMS and emails like an interrupt. Subscribe once, receive events as they land in your DB.

const sub = ak.realtime.subscribeToSms(identity.id, (msg) => {
  if (msg.direction === 'inbound') {
    handleInboundSms(msg);
  }
});

// Later, when the agent is done:
sub.unsubscribe();

subscribeToEmails works the same way. Both use Supabase Realtime under the hood with a short-lived JWT minted by the API. No polling.

API Reference

new AliasKit(options?)

Create a new client.

ak.identities

create params: name?, emailDomain?, emailUsername?, provisionPhone?, metadata?

ak.emails

waitForCode options: interval? (ms, default 2000), timeout? (ms, default 60000), after? (Date), provider? ('supabase' | 'clerk' | 'auth0' | custom preset)

OTP provider presets

ak.emails.waitForCode can automatically detect common auth providers:

• supabase — detects noreply@*.supabase.io, /auth/v1/verify URLs, and "Supabase" branding.
• clerk — detects *@clerk.* senders, "verification code" subjects, and clerk.* domains.
• auth0 — detects .auth0.com domains, @auth0user.net senders, and /passwordless/verify_redirect URLs.

Pass provider: 'supabase' | 'clerk' | 'auth0' to force a specific preset, or omit it to let the SDK auto-detect.

For non-standard OTP formats, pass a custom ProviderPreset object:

import { AliasKit, ProviderPreset } from 'aliaskit';

const myPreset: ProviderPreset = {
  id: 'my-auth',
  name: 'My Auth Provider',
  detect: (email) => email.from.includes('noreply@myapp.com'),
  extractCode: (text) => {
    const match = text.match(/Your code: (\d{8})/);
    return match ? match[1] : null;
  },
};

const code = await ak.emails.waitForCode(identity.id, { provider: myPreset });

ak.sms

ak.agents

ak.reputation

ak.realtime

All return a RealtimeSubscription with an .unsubscribe() method. Auto-reconnects with exponential backoff on errors.

Error Handling

All errors extend AliasKitError with a machine-readable code:

import { AliasKit, AuthError, EmailTimeoutError, OtpNotFoundError } from 'aliaskit';

try {
  const code = await ak.emails.waitForCode(identity.id);
} catch (err) {
  if (err instanceof EmailTimeoutError) {
    console.log('No email arrived within timeout');
  } else if (err instanceof OtpNotFoundError) {
    console.log('Email arrived but no OTP found:', err.emailSubject);
  }
}

Side use case: end-to-end testing

The same primitives work nicely for testing signup forms in CI: every test run gets a fresh identity, real inbox, and clean state. This was the SDK's original positioning and the core flow is identical — just substitute your test runner for the agent. The OTP extractors, provider presets, and identity cleanup all carry over.

License

MIT