Core Concepts

AliasKit gives AI agents persistent digital identities so they can operate on the internet like human remote workers. Each identity comes with a real email inbox, phone number, virtual cards, and TOTP support. Identities are created once, referenced by ID, and designed for long-running agents.

What is an Identity?

An identity is a persistent digital persona that an AI agent uses to interact with the real world. Each identity includes:

• •Full name - a realistic generated name
• •Email address - a working inbox that receives and sends real mail
• •Phone number - a real US number that sends and receives SMS (plan-dependent)
• •Virtual cards - payment cards for checkout and subscription flows (BYOC model)
• •TOTP - time-based one-time password generation for authenticator-app flows

Identities are created once and persist until you explicitly delete them. They are designed for agents that need to maintain accounts, subscriptions, and ongoing relationships with services over time.

Identities are isolated per API key. One key's identities cannot access another key's data, even within the same account. See the SDK reference for usage.

Email Inbox

Every identity gets a unique email address under aliaskit.com. These are real inboxes that receive real email.

How it works

1. A service sends an email to the identity's address (for example, a verification code or account notification). 2. Resend receives the inbound email via webhook. 3. AliasKit parses and stores the email, extracting any OTP codes automatically. 4. Your agent retrieves the email or waits for a matching code.

Sending email

Identities can send outbound email through the API. See the SDK reference for all email methods.

Storage

Emails are stored for the lifetime of the identity. When you delete an identity, all associated emails are permanently removed.

Phone and SMS

Each identity can be assigned a real US phone number powered by Twilio.

Inbound SMS

When someone sends a text to the identity's number, AliasKit captures it via Twilio webhook and stores it for retrieval.

Outbound SMS

Identities can send SMS messages through the API.

See the SDK reference for all SMS methods including waitForCode.

Virtual Cards

AliasKit supports virtual payment cards through a Bring Your Own Card (BYOC) zero-knowledge model. You connect your own card issuer, and AliasKit provisions virtual card numbers linked to your identities without ever storing the underlying card details.

This lets agents handle checkout flows, subscribe to services, and make payments on behalf of users.

How BYOC works

1. You configure your card issuer connection in the AliasKit dashboard. 2. When an identity needs a card, AliasKit requests a virtual card number from your issuer. 3. The virtual card is linked to the identity and can be used for transactions. 4. AliasKit never stores raw card numbers. Card data stays with your issuer.

See the SDK reference for card creation and management methods.

TOTP

AliasKit can register TOTP (Time-based One-Time Password) secrets and generate valid codes on demand. This lets agents complete authenticator-app verification flows without a real authenticator app.

When a service displays a TOTP setup QR code, extract the secret and register it with AliasKit. You can then generate valid codes on demand. See the SDK reference for usage.

Realtime Events

AliasKit supports WebSocket subscriptions so your agent can receive events in real time instead of polling.

Subscribing

Connect to the WebSocket endpoint and subscribe to events for a specific identity. See the SDK reference for subscription methods.

Available events

• •email.received - a new email arrived in the identity's inbox
• •email.sent - an outbound email was sent successfully
• •sms.received - a new SMS was received
• •sms.sent - an outbound SMS was sent successfully
• •card.transaction - a transaction occurred on the identity's virtual card

Realtime events are useful for agents that need to react immediately to inbound messages rather than polling on an interval.

API Keys and Auth

All API requests require an API key passed in the Authorization header:

Authorization: Bearer ak_live_abc123...

Key format

API keys use the prefix ak_live_ for production keys and ak_test_ for test-mode keys.

Scopes

Keys can be scoped to limit access. Available scopes include:

• •identities:read - list and retrieve identities
• •identities:write - create and delete identities
• •emails:read - read inbox contents
• •sms:read - read SMS messages
• •sms:write - send SMS messages
• •cards:read - view virtual card details
• •cards:write - create and manage virtual cards

Storage

API keys are hashed with SHA-256 before storage. AliasKit never stores your raw key after initial generation. If you lose a key, you must generate a new one.

Rate limits

Each key has its own rate limit bucket. See Rate Limiting for details.

Data Isolation

All data is isolated per API key. This means:

• •Identities created with one key are invisible to another key
• •Email and SMS data cannot be accessed across keys
• •Virtual card data is scoped to the key that provisioned it
• •Metadata and tags are scoped to the key that created them

This isolation makes AliasKit safe for multi-agent workflows. Give each agent or service its own API key, and their data stays completely separate.

Metadata and Tagging

Every identity supports a metadata field that accepts arbitrary JSON. Use it to tag identities for filtering, reporting, or correlation with your own systems.

Common uses

• •framework - the agent framework using this identity (crewai, autogen, langchain)
• •role - what role this identity serves (customer-support, procurement, research)
• •team - group identities by team or department
• •external_id - link back to your own system's ID for cross-referencing

Metadata is stored as a JSON object and can be queried via the API when listing identities.

Identity Status Lifecycle

Identities move through three statuses:

• •active - the identity is fully functional, its inbox, phone number, and cards are live
• •suspended - the identity is paused, inbound messages are held but the identity cannot be used for new actions
• •deleted - the identity and all associated data (emails, SMS, cards, TOTP secrets) are permanently removed

active -> suspended -> active    (reversible)
active -> deleted                (permanent)
suspended -> deleted             (permanent)

Identities are designed to stay active for the long term. Suspend an identity when you need to temporarily pause an agent without losing its history.

Rate Limiting

API requests are rate-limited per key. When you exceed your limit, the API returns a 429 Too Many Requests response with a Retry-After header.

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 2 seconds.",
  "retry_after": 2
}

Rate limits vary by plan. See Plans and Limits for the exact numbers.

Plans and Limits

Phone provisioning

All plans include at least one phone number. Additional numbers can be provisioned up to your plan limit. Enterprise customers can request dedicated number pools.

Scoped keys

All plans support API keys. Developer and above get full scope control, letting you create keys with restricted permissions for different agents or services.

Custom Domains

Pro and Enterprise plans can configure custom email domains so identity emails use your own domain (for example, agent@yourcompany.com) instead of the default aliaskit.com.

Custom domains are configured through the AliasKit dashboard. You add your domain, verify DNS records, and all new identities on your account will use the custom domain.