Returning User Verification

Stile can reuse a user's prior verification within your organization instead of forcing a new camera or ID flow on every visit. This guide covers the same-operator three-tier model and the strength, age-tier, and expiry rules that decide when a user must verify again. For reuse between different operators, read Trust Reuse.

The three-tier model

When a user arrives, the system checks three tiers in order. The first tier that succeeds is used — no unnecessary steps.

Tier 1: VP tokens

A VP token is a signed JWT stored in the browser's localStorage, scoped to the current origin. It is issued automatically after a successful verification and contains:

• A verified person ID (opaque identifier)
• The credential method and age tier
• An expiry timestamp
• A signature from Stile's servers

The lifecycle:

1. User completes a full verification (Tier 3) or the OTP reuse flow (Tier 2).
2. Stile issues a VP token and the widget stores it in localStorage.
3. On the next visit, the widget finds the token and sends it to Stile for validation.
4. If valid, the user passes instantly — no camera, no OTP, no friction.

If you orchestrate this yourself, pass the token as vp_token when creating a session. A malformed, expired, or revoked token returns 400 vp_token_invalid — treat that as "no token" and fall through to Tier 2.

Tier 2: Organization-scoped lookup with OTP

localStorage is scoped per origin, so a token can be unavailable after the user changes browser, device, or origin. Stile can then look up a credential previously created by your organization and require an email OTP before reusing it:

Check for an existing credential server-side

For a user your application has already authenticated, your backend can ask whether your organization holds a credential that meets the required assurance level:

curl -X POST https://api.stile.id/v1/verified_person/lookup \
  -H "Authorization: Bearer stile_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "min_strength": "document_capture"
  }'

const result = await stile.verifiedPersons.lookup({
  email: "user@example.com",
  min_strength: "document_capture",
  max_age: "30",
});

if (result.verified) {
  console.log(result.verified_person_id);
  console.log(result.credentials);
  // [{ method: "MDL", strength: "MDL", verified_at: "...", expires_at: "..." }]
}

See the Verified Person API for the full parameter and response reference.

Reuse at session creation

You don't have to orchestrate the lookup yourself. Pass the reuse parameters on POST /v1/verification_sessions and Stile runs the flow as part of the session:

If the workflow requires ownership proof, the session's requires_email_otp field is true and the user must complete the OTP gate before reuse. Otherwise requests fail with 400 email_not_verified or 400 otp_not_proven. When no reusable credential matches your filters, session creation returns 400 no_matching_vp. Repeated accept_existing attempts for the same email are limited to 10 per 15-minute window; the eleventh returns 429 accept_existing_rate_limited.

Email binding

VP tokens are bound to the email address used during verification. This prevents token sharing:

• If user A verifies with alice@example.com, their VP token is bound to that email.
• If user B tries to use the same device, a different email triggers re-verification.
• Changing the email on an existing session forces a full Tier 3 verification.

Credential strength ranking

Not all verification methods carry the same weight. Stile ranks credential methods by strength:

This is a compatibility taxonomy and includes reserved values; it is not a list of methods you can publish today. mid, eudi_pid, facial_age, carrier_lookup, open_banking, student, and parental_consent are not currently runnable workflow steps. Methods not listed map onto this ranking: available selfie_match and selfie_liveness count at document_capture strength; reserved student and parental_consent values count at self_attestation strength.

A stronger credential always satisfies a weaker requirement: a user verified with document_capture (rank 5) satisfies a request for self_attestation (rank 1) without re-verifying. The reverse is never true — a self_attestation credential cannot satisfy a document_capture requirement, and the user must complete a step-up verification.

Age tier compatibility

Age tiers follow a strict hierarchy:

min_age_21 --> satisfies min_age_18, min_age_16, and min_age_13
min_age_18 --> satisfies min_age_16 and min_age_13
min_age_16 --> satisfies min_age_13
min_age_13 --> satisfies min_age_13 only

A credential proving min_age_21 automatically satisfies any lower requirement. A weaker tier (e.g. min_age_16) can never satisfy a stronger one (e.g. min_age_21) — that, too, routes the user to a step-up verification.

Credential expiry

Credentials expire based on jurisdiction compliance rules. The default expiry is 365 days from the date of verification. When a credential expires:

• Tier 1 (VP token) stops working — the token is rejected during validation.
• Tier 2 (email lookup) finds the credential but sees it's expired.
• The user is routed to Tier 3 for a full re-verification.

You can also enforce a stricter recency bar than the credential's own expiry — pass max_age at lookup or session creation to refuse credentials older than your policy allows.

Step-up verification

A valid, non-expired credential can still be insufficient if the new request requires a stronger method or a higher age tier.

Example: A user verified with self_attestation (rank 1) visits a site that requires document_capture (rank 5). Their existing credential doesn't meet the requirement, so they complete a new verification with the stronger method.

After the step-up, the new (stronger) credential replaces the old one. The user now holds a document_capture credential that satisfies both document_capture and self_attestation requirements going forward.

OTP is not proof of age

A common misconception: completing an OTP challenge does not prove anything about the user's age or identity.

• OTP proves: "This person controls this email address."
• OTP enables: Reuse of an existing, previously-verified credential.
• OTP does not prove: Age, identity, or anything else.

The actual proof always comes from the underlying verification credential, such as a verified ID scan or mobile driver's license. The OTP is a gate that ensures only the rightful owner of the email can access the credential linked to it.

Next steps