Core Concepts

AIdenID starts with a site-owned clearance decision, then uses supporting identity, inbox, target, webhook, and audit primitives to make that decision explainable and enforceable.

Clearance decisions

A clearance decision is the per-request answer AIdenID returns before sensitive origin logic runs. Each decision includes an actor class, route policy, action, reason, rollout mode, and evidence references for later audit.

The six possible outcomes are:

• allow — let the request continue
• throttle — slow the actor down with a bounded retry window
• queue — defer the work for human or asynchronous review
• sandbox — route to a constrained experience or low-risk path
• deny — reject the request
• price_required — require payment or a higher entitlement before continuing

Actor classes

AIdenID labels traffic instead of pretending to know whether a caller is "really human." Route policies can distinguish:

• verified_agent — cryptographic proof, DPoP, audience-bound session, and policy checks passed
• signed_agent — signed request proof exists, but the full verified path is incomplete or shadowed
• likely_human — confidence signals look human enough for the configured route policy
• suspicious_automation — automation signals require throttle, queue, sandbox, or deny behavior
• unknown — insufficient proof or confidence for a stronger label

Route policy

Route policy maps host, path template, method, actor class, quotas, risk tier, and rollout mode to a deterministic outcome. Teams usually start in observe, compare counterfactual decisions inshadow, then enforce high-confidence routes one by one.

Cryptographic proof

The strict path verifies HTTP Message Signatures, DPoP proofs, exchanged session tokens, replay windows, issuer key epochs, and audience binding. Raw upstream credentials are stripped at the edge or origin; downstream services receive an AIdenID decision context instead.

Revocation epochs

AIdenID can revoke sessions, grants, issuers, and delegated chains by bumping an epoch. Strict routes deny revoked actors before grant lookup so attackers do not learn whether a grant exists.

Audit evidence

Decisions can emit OCSF-shaped events, signed webhooks, live dashboard updates, and Merkle-rooted transparency-log commitments. The audit path records policy versions, issuer rotations, revocation epochs, sampled decision batches, and evidence bundle roots.

Supporting identities

A supporting identity represents a scoped actor, issuer workflow, or disposable inbox provisioned on demand. It is not the whole product; it gives the clearance layer issuer context, lineage, budgets, TTLs, and inbox evidence when a workflow needs them. Each identity has:

• A unique ID (e.g., ident_a1b2c3d4e5)
• A unique email address (e.g., a1b2c3d4e5@inbox.aidenid.com)
• A human-readable label
• A lifecycle status
• A time-to-live (TTL) after which it expires
• Optional metadata for your own tracking

Identities are always scoped to a project, which is itself scoped to an organization. This hierarchy provides isolation between different teams, environments, or use cases.

Inboxes

Identities that need email evidence get a dedicated inbox capable of receiving mail. When an email arrives at the identity's address, AIdenID processes it through the extraction pipeline to detect and extract authentication codes.

Inboxes are active for the duration of the identity's lifecycle. Once squashed or expired, the inbox is deactivated and no longer accepts email.

Extraction

Extraction is the process of detecting and pulling authentication codes or links from inbound emails. AIdenID supports:

• OTP codes — Numeric or alphanumeric one-time passwords
• Magic links — Unique URLs for passwordless authentication
• Confirmation links — Email verification URLs

Each extraction includes a confidence score (0.0 to 1.0) indicating how certain the system is about the extracted value. Production extractions typically have confidence scores above 0.95.

Events

Every meaningful action in AIdenID produces an event. Events are the basis for webhook delivery, dashboard streams, and audit trails. Key event types include:

• decision.evaluated — A clearance decision was made for a request
• policy.published — A route policy bundle changed
• issuer_key.rotated — An issuer key rotation was accepted
• revocation.epoch_bumped — A session, grant, or issuer epoch was revoked
• email.received — An email arrived at an identity inbox
• extraction.completed — A code or link was extracted
• identity.provisioned — A new identity was created
• identity.extended — An identity TTL was extended
• identity.squashed — An identity was revoked
• identity.expired — An identity TTL elapsed

Lifecycle

Identities follow a defined lifecycle with clear state transitions. See the Identity Lifecycle page for a deep dive.

The five lifecycle states are:

1. Provisioned — Created, inbox active
2. Active — Receiving and processing email
3. Extended — TTL extended beyond original duration
4. Squashed — Manually revoked
5. Expired — TTL elapsed naturally

Projects and organizations

AIdenID uses a two-level hierarchy for resource isolation:

• Organization — The top-level entity. Represents your company or team. Contains one or more projects.
• Project — A namespace within an organization. Identities, webhooks, and other resources are scoped to a project. Use separate projects for staging vs. production, or for different product lines.

API keys

API keys authenticate requests and determine access scope. Each key is bound to an organization and can be restricted to specific scopes (e.g., identities:read, webhooks:write). See Authentication for details.

Idempotency

All mutation endpoints require an Idempotency-Key header. This ensures that retrying a failed request (e.g., due to a network timeout) does not create duplicate resources. AIdenID stores the result of the original request and returns it on subsequent calls with the same idempotency key.

Webhooks

Webhooks allow you to receive real-time notifications when events occur. Instead of polling the API, register an HTTPS endpoint and AIdenID will push events to you. Payloads are signed with HMAC-SHA256 so you can verify authenticity. See Webhook Integration.

Buyer and support audiences

AIdenID primarily serves site owners that need a decision point for agent traffic. Supporting APIs also serve agent issuers, QA teams, and human inbox users:

For a detailed comparison, see Human vs Agent.

Trials

All paid agent plans include a 7-day free trial with full access to plan features. Trials are scoped per organization — each org gets one trial per plan. During the trial, identities and webhooks work exactly as they do on a paid subscription. At the end of the trial, you can convert to a paid plan via Stripe checkout or let the trial expire. See Trials API.

Child identities

Some flows require multiple email addresses. For example, a signup flow might ask for a primary email and a recovery email. AIdenID supports child identities — subordinate identities linked to a parent. Child identities share the parent's project and can be squashed individually or in bulk through the parent.