Start SCA factor enrollment

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"
}'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({type: 'TOTP'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/sca/factors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"type\": \"TOTP\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/sca/factors")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "type": "TOTP",
  "secret": "<string>",
  "secretBase32Encoded": "<string>",
  "totpUri": "otpauth://totp/Grid:customer@example.com?secret=ABC123&issuer=Grid"
}

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "message": "<string>",
  "details": {}
}

{
  "status": 409,
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

Strong Customer Authentication

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 only one passkey. Starting a passkey enrollment when one is already enrolled returns 409 (PASSKEY_ALREADY_ENROLLED) — delete it 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 --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"
}'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({type: 'TOTP'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/sca/factors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"type\": \"TOTP\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/sca/factors")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "type": "TOTP",
  "secret": "<string>",
  "secretBase32Encoded": "<string>",
  "totpUri": "otpauth://totp/Grid:customer@example.com?secret=ABC123&issuer=Grid"
}

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "message": "<string>",
  "details": {}
}

{
  "status": 409,
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

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

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:customer@example.com?secret=ABC123&issuer=Grid"

List enrolled SCA factors

Confirm SCA factor enrollment

⌘I

Using the API

API documentation

Start SCA factor enrollment

Authorizations

Query Parameters

Body

Response