Consumer API

Human-facing endpoints for individual consumers. Unlike the agent API which uses API keys, the consumer API uses passwordless magic-link authentication to create browser sessions.

Sign up

Create a new consumer account. A magic-link verification email is sent to the provided address.

Request body

curl

curl -X POST https://api.aidenid.com/v1/consumer/signup \
  -H "Content-Type: application/json" \
  -d '{ "email": "alice@example.com" }'

Response 200 OK

{
  "message": "Verification email sent",
  "email": "alice@example.com"
}

Verify magic link

Exchange a magic-link token for a consumer session. The token is delivered via the magic-link email sent during signup or login.

Request body

curl

curl -X POST https://api.aidenid.com/v1/consumer/verify \
  -H "Content-Type: application/json" \
  -d '{ "token": "ml_abc123def456" }'

Response 200 OK

{
  "consumer_id": "csr_m1n2o3p4",
  "org_id": "org_personal_m1n2o3p4",
  "project_id": "proj_default_m1n2o3p4",
  "session_token": "sess_q5r6s7t8",
  "expires_at": "2026-04-13T10:00:00Z"
}

Request login

Send a new magic-link login email to an existing consumer. The resulting token is verified via the same /verify endpoint.

Request body

curl

curl -X POST https://api.aidenid.com/v1/consumer/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "alice@example.com" }'

Response 200 OK

{
  "message": "Login email sent",
  "email": "alice@example.com"
}

Inbox stream (SSE)

Server-Sent Events stream of inbound email events and OTP extractions for the authenticated consumer. Requires a valid consumer session.

curl

curl -N "https://api.aidenid.com/v1/consumer/inbox" \
  -H "Authorization: Bearer sess_q5r6s7t8"

TypeScript

const evtSource = new EventSource(
  "https://api.aidenid.com/v1/consumer/inbox",
  // Note: EventSource does not support custom headers natively.
  // Use a library like eventsource or pass the session as a query param
  // if your backend supports it.
);

evtSource.addEventListener("inbound.received", (e) => {
  const data = JSON.parse(e.data);
  console.log("Inbound event received for identity:", data.identity_id);
});

evtSource.addEventListener("extraction.completed", (e) => {
  const data = JSON.parse(e.data);
  console.log("Extraction completed:", data.type);
});

Event types

List identities

List the authenticated consumer's temporary email identities. Supports pagination.

Query parameters

curl

curl "https://api.aidenid.com/v1/consumer/identities?limit=10&offset=0" \
  -H "Authorization: Bearer sess_q5r6s7t8"

Response 200 OK

{
  "items": [
    {
      "id": "ident_c1d2e3f4",
      "email": "c1d2e3f4@inbox.aidenid.com",
      "label": "twitter-signup",
      "status": "active",
      "created_at": "2026-04-06T08:00:00Z",
      "expires_at": "2026-04-07T08:00:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Create identity

Create a new temporary email identity for the consumer. The number of active identities is limited by the consumer's tier.

Request body

curl

curl -X POST https://api.aidenid.com/v1/consumer/identities \
  -H "Authorization: Bearer sess_q5r6s7t8" \
  -H "Content-Type: application/json" \
  -d '{ "label": "twitter-signup" }'

List notifications

Retrieve notification history for the authenticated consumer, including extraction alerts and identity expiration warnings.

curl

curl "https://api.aidenid.com/v1/consumer/notifications" \
  -H "Authorization: Bearer sess_q5r6s7t8"

Response 200 OK

{
  "items": [
    {
      "id": "notif_u1v2w3",
      "type": "extraction.completed",
      "title": "OTP received for twitter-signup",
      "body": "A redacted code was extracted with 99% confidence",
      "read": false,
      "created_at": "2026-04-06T10:05:02Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Upgrade to paid plan

Start a Stripe checkout session to upgrade the consumer to the human_paid plan. Returns a checkout URL to redirect the user to.

curl

curl -X POST https://api.aidenid.com/v1/consumer/upgrade \
  -H "Authorization: Bearer sess_q5r6s7t8"

Response 200 OK

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

Error codes

Related

• Authentication — agent API key authentication
• Billing API — subscription and invoice management
• Realtime API — SSE streaming for agent integrations