Step-Up Re-Authentication

Challenge high-risk actions like payouts or password resets with fresh Helios verification.

• Reuse external_id to link step-up checks to the original user
• Trigger a fresh liveness verification for risky actions
• Compare new scores to the baseline before approving

Time to complete: ~10 minutes

Prerequisites

• SAGEA_API_KEY set in your environment as Bearer auth.
• Read Send your first API request to create a key.
• Read How Helios works to understand decisions and score thresholds.
• An existing user with a prior verification_id stored under a stable external_id.

Step 1: Trigger re-verification for a risky action

When a high-risk event fires, collect fresh media and POST to https://api.sagea.space/helios/kyc/v2 with the same external_id.

curl -X POST https://api.sagea.space/helios/kyc/v2 \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_12345",
    "front_image_b64": "BASE64_FRONT",
    "liveness_video_b64": "BASE64_VIDEO",
    "options": {"store_media": false}
  }'

Reusing external_id keeps audit history joined: baseline signup check and every step-up share one customer key.

Step 2: Fetch baseline and compare scores

Pull the original and step-up verifications and compare face_match, liveness, and overall before allowing the action.

curl https://api.sagea.space/helios/verifications/helios_vrf_baseline \
  -H "Authorization: Bearer $SAGEA_API_KEY"
 
curl https://api.sagea.space/helios/verifications/helios_vrf_stepup \
  -H "Authorization: Bearer $SAGEA_API_KEY"

A small delta with approved means the same legitimate user. A large face match drop or declined suggests account takeover.

Step 3: Enforce the decision in your app

def allow_payout(stepup):
    if stepup["decision"] == "approved":
        return True
    queue_manual_review(stepup["verification_id"])
    return False

Expire the step-up after 10 minutes so approvals cannot be replayed.

Verify

A successful step-up returns HTTP 200 with the same external_id and a new verification_id. If it fails, check below.

What's next

• Liveness and face match
• Review queue and webhooks
• How Helios works