Skip to content

MCP Session Lifecycle

Verification sessions move through a set of states from creation to completion or termination. Understanding the lifecycle helps you implement polling logic, handle edge cases, and provide clear feedback to users.

In plain terms

A session is created when the agent calls verify_human_presence. The user opens the link and completes the check. The session moves from "pending" to "in progress" to "completed" (live/fake) or to "failed", "expired", or "cancelled".

State Diagram

 Created ──▶ Pending ──▶ In Progress ──▶ Completed (live | fake)
    │           │              │
    │           ▼              ▼
    │        Expired        Failed
    │
    ▼
 Cancelled
State Description
created Session created via verify_human_presence
pending Waiting for user to open verification URL
in_progress User opened URL; capture/analysis in progress
completed Verdict issued (live or fake)
failed User did not pass liveness; may retry with new session
expired Session TTL exceeded; user did not complete in time
cancelled Session cancelled via revoke_session

State Transitions

  1. Created → Pending — Immediate when the session is returned by verify_human_presence.

  2. Pending → In Progress — When the user opens the verification URL and the browser starts capture.

  3. In Progress → Completed — When analysis finishes and a verdict is issued (live or fake).

  4. Pending / In Progress → Expired — When expires_at passes. A background job marks the session expired. The agent should call verify_human_presence again to start a new session.

  5. Pending / In Progress → Failed — If the user does not pass liveness (e.g., spoofing detected, poor capture). The user can try again with a new session.

  6. Pending / In Progress → Cancelled — When the agent calls revoke_session or the user abandons. Optional reason can be logged.

Polling Strategy

For agents that do not use a webhook:

  1. After calling verify_human_presence, surface the verification_url to the user.
  2. Poll check_verification_status every 1–2 seconds.
  3. Stop polling when status is completed, failed, expired, or cancelled.
  4. If completed and verdict is live, call get_verification_result for the full attestation.
  5. If failed or expired, optionally start a new session with verify_human_presence.

Polling interval

Use 1–2 second intervals. Verification typically completes in 1–3 seconds for standard risk and 1–3 seconds for high risk. Avoid polling faster than once per second to reduce load.

Alternative: Webhooks

Instead of polling, configure a webhook in the Developer Portal. When verification completes, Moveris sends an HTTP POST to your URL—no polling needed.

Session Expiration

Setting Default Max Description
Session TTL 300s (5 min) 600s (10 min) How long the session URL remains valid before expiring
Attestation validity 5 min after verdict Configurable How long the signed attestation can be trusted

Sessions in pending or in_progress become expired after the TTL. Completed attestations include an expires_at claim in the JWT so relying parties can enforce validity independently.

Attestation Validity Window

Approach Duration Trade-off
Per-action Single use Most secure, highest friction
Time-windowed 5 min default Balances security and UX for multi-step workflows
Session-based Until session ends Lowest friction, trust decays over time

Moveris MCP (v1) uses time-windowed (5 min default), configurable per API key. The attestation JWT includes an exp claim so agents can verify expiration without calling the API.