Start a 2FA reset

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

Start a 2FA reset

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/sca/factors/reset \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endUserIpAddress": "203.0.113.42"
}
'

201

{
  "resetId": "<string>",
  "livenessAccessToken": "<string>",
  "verificationLink": "<string>",
  "expiresAt": "2025-10-03T12:30:00Z"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Query Parameters

customerId · string · required

The unique identifier of the customer resetting a factor.

Body

application/json

Selects which enrolled factor to reset via the liveness-gated recovery flow, and the IP address the end user is starting the reset from.

factor · enum<string> · required

The enrolled factor to reset.

Available options: SMS_OTP, TOTP, PASSKEY

endUserIpAddress · string · 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:

"203.0.113.42"

Response

201

application/json

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

The reset handle plus the opaque liveness handles a caller relays to the end-user device to complete the liveness check. resetId threads the ceremony together (status and complete reference it). livenessAccessToken and verificationLink are omitted when they are not returned.

resetId · string · required

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

livenessAccessToken · string | null

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

verificationLink · string | null

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

expiresAt · string<date-time> | null

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

Example:

"2025-10-03T12:30:00Z"