LIlightsparkdev
Strong Customer Authentication

Start a 2FA reset

Changed on

Begin recovering a lost enrolled factor via a liveness-gated, poll-based flow. Opens the liveness check and returns a resetId plus the opaque liveness handles (livenessAccessToken / verificationLink) the end user completes it with. Poll GET /sca/factors/reset/{resetId} until liveness passes, then call the complete endpoint.

This endpoint is only meaningful for customers in a region where SCA is required (e.g. EU). For customers outside SCA-regulated regions, this returns 409.

post/sca/factors/reset

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/sca/factors/reset
  • Auth
    HTTP basic

Request body

factor'SMS_OTP' | 'TOTP' | 'PASSKEY' required

A Strong Customer Authentication factor.

FactorDescription
SMS_OTPOne-time code sent by SMS to the customer's verified phone. Requires no prior enrollment.
TOTPTime-based one-time code from an authenticator app. Requires enrollment. Not valid for per-transaction challenges (cannot carry dynamic linking).
PASSKEYWebAuthn passkey assertion. Requires enrollment.
endUserIpAddressstring required

The IP address of the end user's device starting this reset, recorded against the reset by the SCA provider. Supply the customer's address, not your server's — it feeds the provider's risk assessment of the recovery.

Example request

{
  "endUserIpAddress": "203.0.113.42"
}

Response

Reset initiated; the reset handle and liveness material are returned.

resetIdstring required

Identifier for this reset; pass it to the status and complete endpoints.

livenessAccessTokenstring nullable

Access token for the embedded liveness/verification SDK, bound to this reset. Omitted when one is not returned.

verificationLinkstring nullable

Hosted identity-verification page URL for completing liveness. Omitted when one is not returned.

expiresAtstring date-time nullable

Absolute UTC timestamp at the end of the reset window. Omitted when one is not returned.

Example response

{
  "expiresAt": "2025-10-03T12:30:00Z"
}

Changes

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • f11f1e76bdd7Revision changes
    • warning

      added the new PURCHASE_CARD_LIMIT_REACHED enum value to the response property for the response status