Skip to main content
Version: v2.0 (latest)

Choosing the Authentication Mode: login_hint

The scope selects how the face is checked. The standard OIDC login_hint parameter selects what the face is checked against. OIDC Web supports three modes:

Mode 1 — Liveness Only (No login_hint)​

If login_hint is absent, empty, or face:any, OIDC Web performs a pure liveness check: any real, live human face passes. OIDC Web makes no comparison and retains nothing afterwards.

$BASE/oidc/v1/authorize?response_type=code&client_id=$CLIENT_ID
    &scope=openid%20faceauth_dynamic_only
    &redirect_uri=…&state=…&nonce=…&code_challenge=…&code_challenge_method=S256

Use this mode as a human gate against bots and scripted abuse, not as authentication. A liveness-only login identifies no one.

Mode 2 — Hosted Biometric Profile (login_hint = Your User Identifier)​

Send a stable identifier for the user — an email address or an opaque ID from your own user database:

…&scope=openid%20faceauth_dynamic_only&login_hint=jane.doe%40example.com
  • The first time OIDC Web sees an identifier, it enrolls the live face as that user's biometric profile on iProov's servers ("trust on first use").
  • Every subsequent login with the same identifier is a 1:1 verification against that profile: only the same person passes.

Your application asserts the identifier, so pick something stable. Do not alternate between email and user ID for the same person: each distinct value maps to a distinct profile. Profiles are private to your organization. The same email enrolled by another iProov customer maps to an unrelated profile.

If trust on first use is not acceptable for your use case, pre-create the profile from a trusted reference portrait with the user-management API (see Managing Biometric Profiles). Then even the first login verifies against the reference.

Mode 3 — Reference-Photo Verification (via the User-Management API)​

To verify users against a specific reference photo — an ID-document portrait, an HR photo, or any trusted image — pre-create their biometric profile from that photo using the user-management API (see Managing Biometric Profiles), then log them in exactly as in Mode 2 with their identifier. Every login, including the first, is then a 1:1 match against your reference photo:

# 1. Create the profile from your reference photo:
curl -s -X POST "$BASE/oidc/v1/admin/users/biometric_profile/create" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"login_hint": "jane.doe@example.com",
       "portrait": "<base64-encoded-image>",
       "source": "oid"}'

# 2. Then log the user in normally with the same identifier (Mode 2):
#    …&scope=openid%20faceauth_dynamic_only&login_hint=jane.doe%40example.com

Which mode am I in? login_hint decides. An absent, empty, or face:any login_hint is liveness-only. Any other non-empty value selects the hosted-profile mode — and that profile may have been enrolled on first use (Mode 2) or pre-created from a reference photo via the user-management API (Mode 3).