AliasKit
Docs/API Reference

API Reference

REST reference for the AliasKit Identity API. For TypeScript method signatures, parameters, and code examples, see SDKs & Integrations.

Authentication

All API requests require a Bearer token passed via the Authorization header:

Authorization: Bearer ak_live_your_key_here

API keys are created from the dashboard. Each key can be scoped to specific permissions.

Keep your API key secret. Never expose it in client-side code or commit it to version control.

Base URL

All endpoints are relative to:

https://www.aliaskit.com/api/v1

For example, POST /v1/identities resolves to https://www.aliaskit.com/api/v1/identities.

Identities

Identities are the core resource. Each identity gets a unique name, email inbox on aliaskit.com, and optionally a phone number. Identities are persistent and give your AI agents a digital presence they can use across services.

For TypeScript usage, see ak.identities.

Create identity

POST
/v1/identitiesCreate a new persistent identity with email inbox and optional phone number.

Scope: identities:write

For parameters and TypeScript usage, see ak.identities.create().

bash
curl -X POST https://www.aliaskit.com/api/v1/identities \
  -H "Authorization: Bearer ak_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test User",
    "provision_phone": true,
    "metadata": { "test_run": "signup-flow-v2" }
  }'
json
{
  "id": "ident_8f3a1b2c",
  "name": "Test User",
  "email": "test-user-8f3a@aliaskit.com",
  "phone_number": "+12025551234",
  "date_of_birth": "1994-07-12",
  "status": "active",
  "metadata": { "test_run": "signup-flow-v2" },
  "created_at": "2026-04-12T10:00:00Z",
  "updated_at": "2026-04-12T10:00:00Z"
}

List identities

GET
/v1/identitiesList all identities for the authenticated account.

Scope: identities:read

For parameters and TypeScript usage, see ak.identities.list().

bash
curl https://www.aliaskit.com/api/v1/identities \
  -H "Authorization: Bearer ak_live_your_key_here"
json
{
  "data": [
    {
      "id": "ident_8f3a1b2c",
      "name": "Test User",
      "email": "test-user-8f3a@aliaskit.com",
      "phone_number": "+12025551234",
      "status": "active",
      "created_at": "2026-04-12T10:00:00Z"
    }
  ],
  "has_more": false
}

Get identity

GET
/v1/identities/:idRetrieve a single identity by ID.

Scope: identities:read

For TypeScript usage, see ak.identities.get().

bash
curl https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c \
  -H "Authorization: Bearer ak_live_your_key_here"

Update identity

PATCH
/v1/identities/:idUpdate identity fields or metadata.

Scope: identities:write

For parameters and TypeScript usage, see ak.identities.update().

bash
curl -X PATCH https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c \
  -H "Authorization: Bearer ak_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "test_run": "signup-flow-v3" } }'

Delete identity

DELETE
/v1/identities/:idDelete an identity (soft delete). Releases any provisioned phone number.

Scope: identities:write

For TypeScript usage, see ak.identities.delete().

bash
curl -X DELETE https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c \
  -H "Authorization: Bearer ak_live_your_key_here"

Provision phone

POST
/v1/identities/:id/phoneProvision a phone number for an existing identity.

Scope: identities:write

For parameters and TypeScript usage, see ak.identities.provisionPhone().

bash
curl -X POST https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c/phone \
  -H "Authorization: Bearer ak_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "country": "US" }'

Email

Read, send, search, and manage emails for identity inboxes.

For TypeScript usage, see ak.emails.

List emails

GET
/v1/identities/:id/emailsList emails received by this identity's inbox.

Scope: messages:read

For parameters and TypeScript usage, see ak.emails.list().

bash
curl "https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c/emails?limit=10&unread=true" \
  -H "Authorization: Bearer ak_live_your_key_here"
json
{
  "data": [
    {
      "id": "email_a1b2c3",
      "from": "noreply@example.com",
      "to": "test-user-8f3a@aliaskit.com",
      "subject": "Verify your email",
      "snippet": "Your verification code is 482913...",
      "read": false,
      "received_at": "2026-04-12T10:01:30Z"
    }
  ],
  "has_more": false
}

Send email

POST
/v1/identities/:id/emailsSend an email from this identity's address.

Scope: messages:write

For parameters and TypeScript usage, see ak.emails.send().

bash
curl -X POST https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c/emails \
  -H "Authorization: Bearer ak_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "support@example.com",
    "subject": "Account inquiry",
    "body_text": "Hello, I have a question about my account."
  }'

Get email

GET
/v1/identities/:id/emails/:emailIdGet a single email with full body content.

Scope: messages:read

For TypeScript usage, see ak.emails.get().

bash
curl https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c/emails/email_a1b2c3 \
  -H "Authorization: Bearer ak_live_your_key_here"
json
{
  "id": "email_a1b2c3",
  "from": "noreply@example.com",
  "to": "test-user-8f3a@aliaskit.com",
  "subject": "Verify your email",
  "body_text": "Your verification code is 482913. It expires in 10 minutes.",
  "body_html": "<p>Your verification code is <strong>482913</strong>. It expires in 10 minutes.</p>",
  "read": false,
  "received_at": "2026-04-12T10:01:30Z"
}

Mark email read/unread

PATCH
/v1/identities/:id/emails/:emailIdMark an email as read or unread.

Scope: messages:write

For TypeScript usage, see ak.emails.markRead().

Delete email

DELETE
/v1/identities/:id/emails/:emailIdDelete a single email.

Scope: messages:write

For TypeScript usage, see ak.emails.delete().

Search emails

GET
/v1/identities/:id/emails/searchFull-text search across the identity's inbox.

Scope: messages:read

For parameters and TypeScript usage, see ak.emails.search().

bash
curl "https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c/emails/search?query=verification+code&after=2026-04-12T00:00:00Z" \
  -H "Authorization: Bearer ak_live_your_key_here"

SMS

Send, receive, and manage SMS messages for identities with provisioned phone numbers.

For TypeScript usage, see ak.sms.

List SMS

GET
/v1/identities/:id/smsList SMS messages for this identity.

Scope: messages:read

For parameters and TypeScript usage, see ak.sms.list().

bash
curl "https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c/sms?limit=5" \
  -H "Authorization: Bearer ak_live_your_key_here"
json
{
  "data": [
    {
      "id": "sms_x1y2z3",
      "from": "+15551234567",
      "to": "+12025551234",
      "body": "Your code is 847291",
      "direction": "inbound",
      "read": false,
      "received_at": "2026-04-12T10:02:00Z"
    }
  ],
  "has_more": false
}

Send SMS

POST
/v1/identities/:id/smsSend an SMS from this identity's phone number.

Scope: messages:write

For parameters and TypeScript usage, see ak.sms.send().

bash
curl -X POST https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c/sms \
  -H "Authorization: Bearer ak_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15559876543",
    "body": "Hello from AliasKit"
  }'

Get SMS

GET
/v1/identities/:id/sms/:smsIdGet a single SMS message.

Scope: messages:read

For TypeScript usage, see ak.sms.get().

Mark SMS read/unread

PATCH
/v1/identities/:id/sms/:smsIdMark an SMS message as read or unread.

Scope: messages:write

For TypeScript usage, see ak.sms.markRead().

Delete SMS

DELETE
/v1/identities/:id/sms/:smsIdDelete an SMS message.

Scope: messages:write

For TypeScript usage, see ak.sms.delete().

Virtual Cards

Create and manage encrypted virtual payment cards for identity-scoped spending.

For TypeScript usage, see ak.cards.

Create card

POST
/v1/identities/:id/cardsCreate a virtual card. Card data is encrypted client-side before transmission.

Scope: cards:write

For parameters and TypeScript usage, see ak.cards.create().

bash
curl -X POST https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c/cards \
  -H "Authorization: Bearer ak_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "encrypted_data": "YWVzLTI1Ni1nY20tZW5jcnlwdGVkLWRhdGE=",
    "last4": "4242",
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2028,
    "budget_cents": 50000,
    "card_name": "Test purchases"
  }'
json
{
  "id": "card_r4s5t6",
  "identity_id": "ident_8f3a1b2c",
  "last4": "4242",
  "brand": "visa",
  "exp_month": 12,
  "exp_year": 2028,
  "budget_cents": 50000,
  "spent_cents": 0,
  "status": "active",
  "card_name": "Test purchases",
  "created_at": "2026-04-12T10:05:00Z"
}
Card data is never stored in plaintext. The encrypted_data field must be a base64-encoded AES-256-GCM blob encrypted with your account's card key.

List cards

GET
/v1/identities/:id/cardsList all cards for an identity. Returns metadata only, no plaintext card data.

Scope: cards:read

For TypeScript usage, see ak.cards.list().

Get card

GET
/v1/cards/:cardIdGet card metadata. Does not return plaintext card data.

Scope: cards:read

For TypeScript usage, see ak.cards.get().

Reveal card

POST
/v1/cards/:cardId/revealReveal the encrypted card data. Optionally perform a budget check before revealing.

Scope: cards:read

For parameters and TypeScript usage, see ak.cards.reveal().

bash
curl -X POST https://www.aliaskit.com/api/v1/cards/card_r4s5t6/reveal \
  -H "Authorization: Bearer ak_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 2500 }'

Freeze card

POST
/v1/cards/:cardId/freezeTemporarily freeze a card. The card can be unfrozen later.

Scope: cards:write

For TypeScript usage, see ak.cards.freeze().

Unfreeze card

POST
/v1/cards/:cardId/unfreezeUnfreeze a previously frozen card, restoring it to active status.

Scope: cards:write

For TypeScript usage, see ak.cards.unfreeze().

Cancel card

POST
/v1/cards/:cardId/cancelPermanently cancel a card. This action cannot be undone.

Scope: cards:write

For TypeScript usage, see ak.cards.cancel().

Get card limits

GET
/v1/cards/:cardId/limitsGet current spending limits and usage for a card.

Scope: cards:read

For TypeScript usage, see ak.cards.budget().

json
{
  "card_id": "card_r4s5t6",
  "budget_cents": 50000,
  "spent_cents": 12300,
  "remaining_cents": 37700,
  "status": "active"
}

Update card limits

PATCH
/v1/cards/:cardId/limitsUpdate a card's spending limit or reset the spend counter.

Scope: cards:write

For parameters and TypeScript usage, see ak.cards.updateBudget().

Get card transactions

GET
/v1/cards/:cardId/transactionsGet the transaction history for a card.

Scope: cards:read

For parameters and TypeScript usage, see ak.cards.activity().

TOTP

Register, manage, and generate time-based one-time passwords for two-factor authentication flows.

For TypeScript usage, see ak.totp.

Register TOTP

POST
/v1/identities/:id/totpRegister a TOTP secret for an identity.

Scope: identities:write

For parameters and TypeScript usage, see ak.totp.register().

bash
curl -X POST https://www.aliaskit.com/api/v1/identities/ident_8f3a1b2c/totp \
  -H "Authorization: Bearer ak_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "JBSWY3DPEHPK3PXP",
    "service_name": "example.com"
  }'

List TOTP entries

GET
/v1/identities/:id/totpList all TOTP entries for an identity.

Scope: identities:read

For TypeScript usage, see ak.totp.list().

Get TOTP code

POST
/v1/identities/:id/totp/:totpId/codeGet the current TOTP code and time remaining.

Scope: identities:read

For TypeScript usage, see ak.totp.getCode().

json
{
  "code": "482913",
  "remaining_seconds": 17
}

Delete TOTP entry

DELETE
/v1/identities/:id/totp/:totpIdRemove a TOTP entry from an identity.

Scope: identities:write

For TypeScript usage, see ak.totp.delete().

Realtime

Get authentication tokens for live event subscriptions over WebSocket. Built on Supabase Realtime.

For TypeScript usage, see ak.realtime.

Get realtime token

POST
/v1/realtime/tokenGet a short-lived token for subscribing to realtime events.

Scope: messages:read

For parameters and TypeScript usage, see ak.realtime.subscribe().

Realtime subscriptions are handled by the SDK. The token endpoint exists to authenticate WebSocket connections. Use ak.realtime.subscribe() in the TypeScript SDK to listen for events.

Errors

All errors follow a consistent format:

json
{
  "error": {
    "type": "invalid_request",
    "message": "The 'to' field is required when sending an email.",
    "param": "to",
    "status": 400
  }
}

Common error types:

  • •invalid_request (400) - Missing or invalid parameters
  • •unauthorized (401) - Missing or invalid API key
  • •forbidden (403) - API key lacks the required scope
  • •not_found (404) - Resource does not exist
  • •conflict (409) - Resource already exists (e.g. duplicate handle)
  • •rate_limited (429) - Too many requests, retry after the Retry-After header
  • •internal_error (500) - Something went wrong on our end

For a full guide on error handling, see Error Handling.

SDKs & IntegrationsConcepts