Skip to main content

​
The Challenge Object

A challenge is a single verification a user has to complete — an OTP, a magic link, a passkey prompt, etc. One challenge tracks one attempt at proving something: that the user owns this email, that they’re really the one signing in, that they consent to a sensitive action.

​
Attributes

​
string
required
Unique identifier.
​
string
required
The app this challenge belongs to.
​
string
The user being challenged. May be empty for anonymous flows (e.g. a sign-up before the user record exists).
​
string
required
Why this challenge exists. One of:
  • authenticate — primary login
  • mfa — second factor after primary auth
  • step_up — re-verify before a sensitive action
  • verify_contact — confirm an email or phone number
  • verify_identity — KYC / identity verification
  • change_identifier — confirm a new email or phone before swapping
  • custom — triggered by you, for your own flow
​
string
required
How the user will prove themselves. One of:email_otp, sms_otp, magic_link, totp, backup_code, webauthn, oauth, push, plaid_idv
​
string
required
Current state. One of:
  • pending — issued, waiting on the user
  • completed — user passed
  • failed — too many wrong attempts
  • expired — expires_at passed before completion
  • cancelled — voided by you or the user
  • denied — explicitly rejected (e.g. user said “this wasn’t me”)
​
string
The email or phone the challenge was sent to, when applicable.
​
string
Free-form label for what action this challenge guards (e.g. login, delete_account, wire_transfer). Useful for filtering and audit.
​
object
Structured data describing the action. Echoed back when the challenge completes so you can act on it.
​
string
Who started the challenge: user, admin, system, or your own value.
​
string
ID of the initiator.
​
string
If this challenge is a follow-up to another (e.g. MFA after primary auth), the parent’s ID.
​
integer
Number of guesses made so far.
​
integer
How many guesses are allowed before the challenge fails. Default 3.
​
integer
max_attempts - attempts. Convenience field.
​
integer
Lifetime in seconds from creation. Default 600.
​
string
Where the user is sent after completing a magic link or OAuth challenge.
​
string
Shareable short URL for magic-link and similar flows. Only present once a short token has been minted.
​
object
Arbitrary key/value data you attached when creating the challenge.
​
object
Additional context captured by Scute (request origin, flow hints, etc.).
​
object
User agent / device fingerprint of the requester, when available.
​
string
IP that initiated the challenge.
​
string
required
ISO 8601 timestamp.
​
string
required
When the challenge stops accepting answers.
​
string
When the OTP / magic link was successfully sent.
​
string
When the user first opened the magic link or OTP message, if tracked.
​
string
When the user passed the challenge.
​
string
When the challenge reached its final state (verified, failed, expired, cancelled, or denied).

​
Example