Quickstart

Plan your first clearance gate in under 5 minutes. AIdenID helps a site decide, per request, whether agent-attributable traffic should be allowed, throttled, queued, sandboxed, denied, or priced.

Step 1: Pick the route to protect

Start with one route where agent traffic has real cost or risk: checkout, account settings, support, patient or benefits data, admin actions, or high-cost inventory reads.

{
  "host": "app.example.com",
  "route": "/checkout",
  "method": "POST",
  "initial_mode": "observe"
}

Step 2: Choose initial outcomes

In observe mode, AIdenID records what it would have done without blocking production traffic. Use that stream to set a policy for each actor class before moving to shadow or enforce.

{
  "verified_agent": "allow",
  "signed_agent": "queue",
  "likely_human": "allow",
  "suspicious_automation": "sandbox",
  "unknown": "throttle"
}

Step 3: Verify the evidence path

A useful clearance rollout needs evidence from day one: decision events, route analytics, revocation tests, and a proof run against staging traffic.

• Confirm the dashboard shows actor-class mix and six-outcome counts
• Confirm a revoked session denies before grant lookup on strict routes
• Export an OCSF-shaped decision sample for your SIEM or data lake
• Run an authorized staging swarm to produce video, logs, and a report

Supporting identity API prerequisites

• An AIdenID account (sign up at aidenid.com)
• Your API key, organization ID, and project ID from the dashboard
• curl or any HTTP client

Identity Step 1: Create an identity

Provision a scoped disposable email identity when your issuer, QA, or demo workflow needs inbox evidence. This creates a unique inbox that can receive email and extract verification codes.

curl -X POST https://api.aidenid.com/v1/identities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Org-Id: YOUR_ORG_ID" \
  -H "X-Project-Id: YOUR_PROJECT_ID" \
  -H "Idempotency-Key: <GENERATED_UNIQUE_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "my-first-identity",
    "ttl_hours": 24
  }'

You will receive a response with your new identity:

{
  "id": "ident_a1b2c3d4e5",
  "email": "a1b2c3d4e5@inbox.aidenid.com",
  "label": "my-first-identity",
  "status": "provisioned",
  "created_at": "2026-04-04T10:00:00Z",
  "expires_at": "2026-04-05T10:00:00Z"
}

Identity Step 2: Use the email in an authorized flow

Use the generated email address (a1b2c3d4e5@inbox.aidenid.com) in a customer-controlled signup, invite, or verification flow. AIdenID will intercept the incoming email automatically.

Identity Step 3: Poll for the extraction

Once the verification email arrives, AIdenID extracts the authentication code automatically. Poll the extraction endpoint:

curl https://api.aidenid.com/v1/identities/ident_a1b2c3d4e5/extractions/latest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Org-Id: YOUR_ORG_ID" \
  -H "X-Project-Id: YOUR_PROJECT_ID"

When the extraction is ready:

{
  "id": "ext_m1n2o3",
  "identity_id": "ident_a1b2c3d4e5",
  "type": "otp",
  "has_secret": true,
  "redacted_value": "***",
  "extracted_at": "2026-04-04T10:05:02Z",
  "confidence": 0.99
}

Identity Step 4: Use the extracted code

Use the extracted secret from your secure runtime flow to complete the verification step. Do not log raw OTP or link values in application logs, traces, or analytics events.

Identity Step 5: Clean up

When you are done with the identity, squash it to revoke the inbox and prevent further email delivery:

curl -X POST https://api.aidenid.com/v1/identities/ident_a1b2c3d4e5/squash \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Org-Id: YOUR_ORG_ID" \
  -H "X-Project-Id: YOUR_PROJECT_ID" \
  -H "Idempotency-Key: <GENERATED_UNIQUE_KEY>"

Python example

Here is the same flow in Python:

import requests
import time

API = "https://api.aidenid.com"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "X-Org-Id": "YOUR_ORG_ID",
    "X-Project-Id": "YOUR_PROJECT_ID",
    "Content-Type": "application/json",
}

# Create identity
identity = requests.post(
    f"{API}/v1/identities",
    headers={**HEADERS, "Idempotency-Key": "qs-create-001"},
    json={"label": "quickstart", "ttl_hours": 24},
).json()

print(f"Identity: {identity['id']}")

# ... use the email in your signup flow ...

# Poll for extraction
for _ in range(30):
    resp = requests.get(
        f"{API}/v1/identities/{identity['id']}/extractions/latest",
        headers=HEADERS,
    )
    if resp.status_code == 200:
        extraction = resp.json()
        print(f"Extraction ready: {extraction['type']}")
        break
    time.sleep(2)

# Clean up
requests.post(
    f"{API}/v1/identities/{identity['id']}/squash",
    headers={**HEADERS, "Idempotency-Key": "qs-squash-001"},
)

TypeScript example

The same flow in TypeScript:

const API = "https://api.aidenid.com";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "X-Org-Id": "YOUR_ORG_ID",
  "X-Project-Id": "YOUR_PROJECT_ID",
  "Content-Type": "application/json",
};
const fetchWithTimeout = async (url: string, init: RequestInit = {}, timeoutMs = 10_000) => {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), timeoutMs);
  try {
    return await fetch(url, { ...init, signal: controller.signal });
  } finally {
    clearTimeout(timeout);
  }
};

// Create identity
const identity = await fetchWithTimeout(`${API}/v1/identities`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "qs-create-001" },
  body: JSON.stringify({ label: "quickstart", ttl_hours: 24 }),
}).then((r) => r.json());

console.log("Identity:", identity.id);

// ... use the email in your signup flow ...

// Poll for extraction
let consecutiveUpstreamFailures = 0;
for (let i = 0; i < 30; i++) {
  const resp = await fetchWithTimeout(
    `${API}/v1/identities/${identity.id}/extractions/latest`,
    { headers }
  );
  if (resp.status >= 500) {
    consecutiveUpstreamFailures += 1;
    if (consecutiveUpstreamFailures >= 3) {
      throw new Error("Circuit breaker opened after repeated upstream errors");
    }
    await new Promise((r) => setTimeout(r, 2000));
    continue;
  }
  consecutiveUpstreamFailures = 0;
  if (resp.ok) {
    const extraction = await resp.json();
    console.log("Extraction ready:", extraction.type);
    break;
  }
  await new Promise((r) => setTimeout(r, 2000));
}

// Clean up
await fetchWithTimeout(`${API}/v1/identities/${identity.id}/squash`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "qs-squash-001" },
});

Quickstart for humans

If you are a human consumer looking for disposable email addresses (not building an agent), the process is simpler:

1. Visit aidenid.com/consumer/signup and enter your personal email
2. Click the magic link in your inbox to verify your account
3. Create a disposable email from the web inbox — it appears instantly
4. Use the disposable address for signups. OTPs and magic links appear in your inbox in real time via SSE
5. OTPs are also forwarded to your personal email so you never miss one

Quickstart for the agent free tier

No signup or API key needed. Create a disposable identity with a single request:

# Create a free identity (IP-keyed, 1 per IP, 24h TTL)
curl -X POST https://api.aidenid.com/v1/free/identity \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <GENERATED_UNIQUE_KEY>"

# Poll for the extraction
curl "https://api.aidenid.com/v1/free/identity/{id}/extraction?token={token}"

See the Free Tier API for full documentation.

Next steps

• Read the Identities API reference for all available operations
• Set up webhooks to receive real-time extraction events instead of polling
• Learn about identity lifecycle management
• Configure the MCP server for direct LLM tool calling
• Try the free tier for zero-signup experimentation
• Learn about human vs agent differences