Endpoints for authorizing money-movement operations that require Strong Customer Authentication. Relevant only for customers in a region where SCA is required (e.g. EU); customers outside SCA-regulated regions never see an SCA challenge and these endpoints return 409.
openapi: 3.1.0
info:
title: Grid Agent Management Strong Customer Authentication API
description: 'API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/.
'
version: '2025-10-13'
contact:
name: Lightspark Support
email: support@lightspark.com
license:
name: Proprietary
url: https://lightspark.com/terms
servers:
- url: https://api.lightspark.com/grid/2025-10-13
description: Production server
security:
- BasicAuth: []
- AgentAuth: []
tags:
- name: Strong Customer Authentication
description: Endpoints for authorizing money-movement operations that require Strong Customer Authentication. Relevant only for customers in a region where SCA is required (e.g. EU); customers outside SCA-regulated regions never see an SCA challenge and these endpoints return 409.
paths:
/sca/factors:
parameters:
- name: customerId
in: query
description: The unique identifier of the customer whose factors are listed or enrolled.
required: true
schema:
type: string
example: Customer:019542f5-b3e7-1d02-0000-000000000001
get:
summary: List enrolled SCA factors
description: 'List the Strong Customer Authentication factors the customer has enrolled.
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`.
'
operationId: listScaFactors
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
responses:
'200':
description: The customer's enrolled SCA factors.
content:
application/json:
schema:
$ref: '#/components/schemas/ScaFactorList'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
post:
summary: Start SCA factor enrollment
description: '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`.
'
operationId: startScaFactorEnrollment
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScaFactorEnrollRequestOneOf'
responses:
'200':
description: Enrollment started; the factor-specific completion material is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ScaFactorEnrollStartOneOf'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer (`CONFLICT`), or a passkey enrollment was requested while one is already enrolled (`PASSKEY_ALREADY_ENROLLED`) — only one passkey per customer is supported.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/sca/factors/confirm:
parameters:
- name: customerId
in: query
description: The unique identifier of the customer confirming a factor enrollment.
required: true
schema:
type: string
example: Customer:019542f5-b3e7-1d02-0000-000000000001
post:
summary: Confirm SCA factor enrollment
description: 'Finalize the factor enrollment started by `POST /sca/factors`. The request
body is discriminated by `type`: for `TOTP`, submit the shared `secret` from
the start call plus the first `code`; for `PASSKEY`, submit the WebAuthn
`credential` the device produced plus the `origin` it was produced against.
The threaded secret/credential binds the confirmation to its enrollment, so
no separate id is needed.
A TOTP confirmation returns one-time recovery codes (shown once); a passkey
confirmation returns the enrolled factor.
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`.
In sandbox, the TOTP code is always `123456`.
'
operationId: confirmScaFactorEnrollment
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScaFactorConfirmRequestOneOf'
responses:
'200':
description: Factor enrolled; the factor-specific result is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ScaFactorConfirmResponseOneOf'
'400':
description: Invalid or incorrect confirmation proof
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/sca/factors/{credentialId}:
parameters:
- name: customerId
in: query
description: The unique identifier of the customer whose factor is being deleted.
required: true
schema:
type: string
example: Customer:019542f5-b3e7-1d02-0000-000000000001
- name: credentialId
in: path
description: The credential id of the enrolled factor to delete (from the factor's `credentialId`).
required: true
schema:
type: string
delete:
summary: Delete an enrolled SCA factor
description: 'Delete an enrolled SCA factor by its credential id. Today only `PASSKEY`
factors carry a `credentialId` and are deletable this way.
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`.
'
operationId: deleteScaFactor
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
responses:
'204':
description: Factor deleted; no content is returned.
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer or factor not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/sca/login/start:
parameters:
- name: customerId
in: query
description: The unique identifier of the customer starting an SCA login.
required: true
schema:
type: string
example: Customer:019542f5-b3e7-1d02-0000-000000000001
post:
summary: Start an SCA login
description: '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`.
'
operationId: startScaLogin
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScaLoginStartRequest'
responses:
'200':
description: SCA login started; factor-specific material is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ScaLoginStart'
'400':
description: Invalid or unknown factor
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/sca/login/complete:
parameters:
- name: customerId
in: query
description: The unique identifier of the customer completing an SCA login.
required: true
schema:
type: string
example: Customer:019542f5-b3e7-1d02-0000-000000000001
post:
summary: Complete an SCA login
description: 'Finalize an SCA login by submitting the proof for the started factor
(`code` for `SMS_OTP` / `TOTP`, or `passkeyAssertion` + `origin` for
`PASSKEY`), echoing the `challengeId` for `SMS_OTP`. Returns the
reported session status.
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`.
In sandbox, the SMS/TOTP code is always `123456`.
'
operationId: completeScaLogin
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScaLoginCompleteRequest'
responses:
'200':
description: SCA login completed; the session status is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ScaLoginComplete'
'400':
description: Invalid or expired proof
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'423':
description: The customer's login is locked (or suspended) after too many failed attempts. `details.lockedUntil` says when they may retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error423'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/sca/record-event:
parameters:
- name: customerId
in: query
description: The unique identifier of the customer the security event is recorded for.
required: true
schema:
type: string
example: Customer:019542f5-b3e7-1d02-0000-000000000001
post:
summary: Record a security event
description: 'Record a client-side security-relevant event for the customer with Grid''s risk engine (e.g. a sign-in, a sensitive view), to
feed adaptive-authentication signals.
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`.
'
operationId: recordSecurityEvent
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RecordSecurityEventRequest'
responses:
'200':
description: Event recorded; the customer's resulting login-security state is returned (including any lockout).
content:
application/json:
schema:
$ref: '#/components/schemas/RecordSecurityEventResponse'
'400':
description: Invalid event type
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'423':
description: The customer's login is locked (or suspended) after too many failed attempts. `details.lockedUntil` says when they may retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error423'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/sca/factors/reset:
parameters:
- name: customerId
in: query
description: The unique identifier of the customer resetting a factor.
required: true
schema:
type: string
example: Customer:019542f5-b3e7-1d02-0000-000000000001
post:
summary: Start a 2FA reset
description: '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`.
'
operationId: startTwoFactorReset
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorResetStartRequest'
responses:
'201':
description: Reset initiated; the reset handle and liveness material are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorResetStart'
'400':
description: Invalid or unknown factor
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'429':
description: Too many reset attempts. Reset initiation is rate-limited to 5 per 24 hours per customer; retry after the window indicated by `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error429'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/sca/factors/reset/{resetId}:
parameters:
- name: customerId
in: query
description: The unique identifier of the customer whose reset status is polled.
required: true
schema:
type: string
example: Customer:019542f5-b3e7-1d02-0000-000000000001
- name: resetId
in: path
description: The reset handle returned by the start call.
required: true
schema:
type: string
get:
summary: Get 2FA reset status
description: 'Poll the status of an in-progress 2FA reset until it reaches the liveness-passed value, after which the reset can be completed.
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`.
'
operationId: getTwoFactorResetStatus
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
responses:
'200':
description: The current reset status.
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorResetStatus'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer or reset not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/sca/factors/reset/{resetId}/complete:
parameters:
- name: customerId
in: query
description: The unique identifier of the customer completing the reset.
required: true
schema:
type: string
example: Customer:019542f5-b3e7-1d02-0000-000000000001
- name: resetId
in: path
description: The reset handle returned by the start call.
required: true
schema:
type: string
post:
summary: Complete a 2FA reset
description: 'Complete a 2FA reset once liveness has passed, clearing the lost factor so
the customer can re-enroll.
For an `SMS_OTP` reset, supply the new `mobile` number in the body — completing
the reset enrolls it as the customer''s number. Other factors need no body.
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`.
'
operationId: completeTwoFactorReset
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFactorResetCompleteRequest'
responses:
'204':
description: Reset completed; no content is returned.
'400':
description: Reset not ready (liveness not yet passed)
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer or reset not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/customers/external-accounts/{externalAccountId}/trust:
parameters:
- name: externalAccountId
in: path
description: The unique identifier of the external account (beneficiary) being trusted.
required: true
schema:
type: string
post:
summary: Start trusting a beneficiary
description: 'Begin trusting (whitelisting) an external account so future sends to it can
skip the per-transaction SCA ceremony. Returns the `scaChallenge` to satisfy
(when one is issued). Complete with
`POST /customers/external-accounts/{externalAccountId}/trust/confirm`.
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`.
'
operationId: startBeneficiaryTrust
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
responses:
'200':
description: Beneficiary trust started; the SCA challenge (if any) is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficiaryTrustStart'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer or external account not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/customers/external-accounts/{externalAccountId}/trust/confirm:
parameters:
- name: externalAccountId
in: path
description: The unique identifier of the external account (beneficiary) being trusted.
required: true
schema:
type: string
post:
summary: Confirm trusting a beneficiary
description: 'Finalize trusting a beneficiary (identified by the `externalAccountId` in the
path) by submitting the SCA proof (`code` for `SMS_OTP` / `TOTP`, or
`passkeyAssertion` + `origin` for `PASSKEY`), echoing the `challengeId` when
one was issued. Returns `trusted: true`.
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`.
In sandbox, the SMS/TOTP code is always `123456`.
'
operationId: confirmBeneficiaryTrust
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficiaryTrustConfirmRequest'
responses:
'200':
description: Beneficiary trusted.
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficiaryTrustConfirm'
'400':
description: Invalid or expired proof
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer or external account not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/customers/external-accounts/{externalAccountId}/untrust:
parameters:
- name: externalAccountId
in: path
description: The unique identifier of the external account (beneficiary) being untrusted.
required: true
schema:
type: string
post:
summary: Start untrusting a beneficiary
description: 'Begin untrusting (removing the trusted mark from) an external account, so
future sends to it are dynamically linked and require the per-transaction SCA
ceremony again. Returns the `scaChallenge` to satisfy (when one is issued).
Complete with
`POST /customers/external-accounts/{externalAccountId}/untrust/confirm`.
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`.
'
operationId: startBeneficiaryUntrust
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
responses:
'200':
description: Beneficiary untrust started; the SCA challenge (if any) is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficiaryTrustStart'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer or external account not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: SCA is not required for this customer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/customers/external-accounts/{externalAccountId}/untrust/confirm:
parameters:
- name: externalAccountId
in: path
description: The unique identifier of the external account (beneficiary) being untrusted.
required: true
schema:
type: string
post:
summary: Confirm untrusting a beneficiary
description: 'Finalize untrusting a beneficiary (identified by the `externalAccountId` in
the path) by submitting the SCA proof (`code` for `SMS_OTP` / `TOTP`, or
`passkeyAssertion` + `origin` for `PASSKEY`), echoing the `challengeId` when
one was issued. Returns `trusted: false`.
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`.
In sandbox, the SMS/TOTP code is always `123456`.
'
operationId: confirmBeneficiaryUntrust
tags:
- Strong Customer Authentication
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficiaryTrustConfirmRequest'
responses:
'200':
description: Beneficiary untrusted.
content:
application/json:
schema:
$ref: '#/components/schemas/BeneficiaryTrust
# --- truncated at 32 KB (170 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightspark/refs/heads/main/openapi/lightspark-strong-customer-authentication-api-openapi.yml