Identity Lifecycle

Every identity in AIdenID follows a defined lifecycle. Understanding these states and transitions is essential for building reliable agent workflows.

Lifecycle states

An identity can be in one of five states:

State transitions

Valid state transitions are:

provisioned --> active       (first email received)
provisioned --> extended     (TTL extended before first email)
provisioned --> squashed     (manually revoked)
provisioned --> expired      (TTL elapsed)

active --> extended          (TTL extended)
active --> squashed          (manually revoked)
active --> expired           (TTL elapsed)

extended --> squashed        (manually revoked)
extended --> expired         (TTL elapsed)

TTL policies

Every identity has a time-to-live (TTL) that determines when it expires. The TTL is set at creation time via the ttl_hours parameter. The maximum TTL depends on your plan:

If you do not specify a ttl_hours value, the default is 24 hours.

Extending identities

You can extend an identity before it expires. This pushes the expiration time forward by the specified number of hours. The total lifetime (original TTL plus extensions) cannot exceed your plan's maximum TTL.

curl -X POST https://api.aidenid.com/v1/identities/ident_a1b2c3d4e5/extend \
  -H "Authorization: Bearer aid_your_api_key" \
  -H "X-Org-Id: org_abc123" \
  -H "X-Project-Id: proj_def456" \
  -H "Idempotency-Key: <GENERATED_UNIQUE_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "additional_hours": 48 }'

Squashing identities

Squashing is the act of immediately revoking an identity. When you squash an identity:

• The inbox is deactivated — no new email will be accepted
• Any in-flight extraction is halted
• The identity transitions to squashed status
• Event history is retained for audit purposes
• This action is irreversible

Always squash identities when you are done with them. This is a security best practice that minimizes the window during which an inbox is active.

Child identity lifecycle

Child identities have their own independent lifecycle, but they are linked to a parent. When you squash a parent identity, you can optionally squash all children in the same operation by calling DELETE /v1/identities/:id/children.

Child identities default to the same TTL as the parent but can be created with a shorter TTL. They cannot outlive the parent.

Expiration behavior

When an identity's TTL elapses, the lifecycle engine automatically transitions it to expired status. This happens asynchronously — there may be a brief delay (typically under 60 seconds) between the TTL elapsed time and the actual state transition.

If you need deterministic cleanup, prefer squashing identities explicitly rather than relying on TTL expiration.

Trial identity lifecycle

During a free trial, identities follow the same lifecycle states as paid identities but are subject to trial-specific constraints:

• Identities created during a trial are bound to the trial period. When the trial expires, all trial identities transition to expired status.
• Converting to a paid plan preserves active trial identities — they continue functioning under the paid plan's quota.
• Trial quotas match the target plan (e.g., a Growth trial allows up to 50 active identities).

Consumer identity lifecycle

Human consumer identities have a simplified lifecycle compared to agent identities:

• Creation: Consumers create disposable emails from the web inbox. Each email is an identity with a tier-limited TTL.
• Active period: Inbound emails trigger OTP extraction. Extracted codes appear in the web inbox via SSE and are forwarded to the consumer's personal email.
• Expiration: Consumer identities expire at the end of their TTL (7 days free, 30 days Personal). There is no extension mechanism for consumer identities.
• Deletion: Consumers can delete (squash) identities early from the web inbox.

Best practices

• Use short TTLs. Set TTLs to the minimum needed for your flow. A signup verification typically completes within minutes — a 1-hour TTL is usually sufficient.
• Squash when done. Do not leave identities active longer than necessary. Squash them as soon as the flow completes.
• Use metadata for tracking. Attach agent names, flow types, or correlation IDs to identity metadata for easier debugging and audit.
• Monitor with webhooks. Subscribe to identity.expired and identity.squashed events to track lifecycle transitions in real time.

Related

• Identities API Reference
• Core Concepts
• Plans and Quotas