Start SCA factor enrollment

Begin enrolling an SCA factor for the customer. Enrollment covers the explicit, opt-in factors a customer chooses to add — the request body’s type selects TOTP or PASSKEY. Returns the factor-specific material needed to finish via POST /sca/factors/confirm.

SMS_OTP is implicit and is not enrolled through this endpoint. Every customer in an SCA-regulated region has a verified phone number from customer creation (via the Contact Verification flows — POST /customers/{customerId}/verify-phone and .../verify-phone/confirm), so SMS is always available as a factor with no extra setup and appears among the customer’s enrolled factors in GET /sca/factors.

A customer may have up to two passkeys. Starting a passkey enrollment with two already enrolled returns 409 (PASSKEY_ALREADY_ENROLLED). Delete one via DELETE /sca/factors/{credentialId} first.

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

Start SCA factor enrollment

cURL

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

200

{
  "type": "TOTP",
  "secret": "<string>",
  "secretBase32Encoded": "<string>",
  "totpUri": "otpauth://totp/Grid:[e-mail]?secret=ABC123&issuer=Grid"
}

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 whose factors are listed or enrolled.

Body

application/json

TOTP Factor Enroll Request

Passkey Factor Enroll Request

Which SCA factor to begin enrolling, selected by type. SMS_OTP is not enrollable (it uses the customer's verified phone), so only TOTP and PASSKEY are valid here.

type · enum<string> · required

Discriminator selecting the TOTP factor. TOTP enrollment needs no other input at start.

Available options: TOTP

Response

200

application/json

Enrollment started; the factor-specific completion material is returned.

Option 1

Option 2

The factor-specific material needed to complete enrollment, keyed by type: a TOTP shared secret + provisioning URI, or the WebAuthn registration options for a passkey.

type · enum<string> · required

Discriminator identifying this as the TOTP enrollment-start payload.

Available options: TOTP

secret · string · required

The raw TOTP shared secret.

secretBase32Encoded · string · required

The Base32-encoded shared secret, suitable for manual entry into an authenticator app that does not scan QR codes.

totpUri · string · required

The otpauth:// provisioning URI (the QR-code payload) the customer's authenticator app scans to enroll the factor.

Example:

"otpauth://totp/Grid:[e-mail]?secret=ABC123&issuer=Grid"