Strong Customer Authentication

Start an SCA login

Changed on

Begin an SCA login for the customer with the chosen factor, opening the end-user SCA session (an exemption gating read / account access beyond the per-transaction window). Returns factor-specific material: SMS_OTP dispatches a code and returns a challengeId + expiresAt; TOTP returns only the factor (the customer reads the code from their app); PASSKEY returns WebAuthn passkeyOptions. Complete with POST /sca/login/complete.

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/login/start

Request

  • Base URL: https://api.lightspark.com/grid/2025-10-13
  • URL: https://api.lightspark.com/grid/2025-10-13/sca/login/start
  • 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.

Response

SCA login started; factor-specific material is returned.

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.
challengeIdstring nullable

The challenge handle for an SMS_OTP login, threaded back on the complete call. Present only for SMS_OTP.

expiresAtstring date-time nullable

Absolute UTC timestamp after which the SMS_OTP code expires. Present only for SMS_OTP.

passkeyOptionsobject nullable

Opaque WebAuthn assertion request options. Present only for PASSKEY; pass to the device's WebAuthn API to produce the assertion submitted on the complete call.

allowedOriginsstring[] nullable

The origins the WebAuthn ceremony may run against. Present only for PASSKEY.

relyingPartyIdstring nullable

The WebAuthn relying-party id. Present only for PASSKEY.

Example response

{
  "expiresAt": "2025-10-03T12:05:00Z",
  "allowedOrigins": [
    "https://app.example.com"
  ],
  "relyingPartyId": "app.example.com"
}

Changes

  • 3966e5d38aadRevision changes
    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • warning

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

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • ccf658daca4bRevision changes
    • warning

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