Record a security event

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.

POST /sca/record-event

Record a security event

cURL

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

200

{
  "eventType": "FAILED_LOGIN_ATTEMPT",
  "suspended": true,
  "failedAttempts": 5,
  "lockedUntil": "2025-10-03T12:15: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 the security event is recorded for.

Body

application/json

Records a client-side security event for the customer so Grid can maintain the customer's login-security state (SCA session revocation and failed-login lockout).

eventType · enum<string> · required

The security event to record:

Value	Effect
RESET_PASSWORD_COMPLETED	Revokes every active SCA session for the customer and clears the failed-login counter.
FAILED_LOGIN_ATTEMPT	Increments the cumulative failed-login counter and escalates the lockout at each milestone: 5 attempts → 15 minutes, 6 → 30 minutes, 7 → 1 hour, 8 → 24 hours, 9 or more → suspension.

Available options: RESET_PASSWORD_COMPLETED, FAILED_LOGIN_ATTEMPT

Example:

"FAILED_LOGIN_ATTEMPT"

endUserIpAddress · string · required

The IP address of the end user's device the event was observed from, recorded against the event by the SCA provider. Supply the customer's address, not your server's — it feeds the provider's risk assessment and the adaptive-authentication signals derived from this event.

Example:

"203.0.113.42"

Response

200

application/json

Event recorded; the customer's resulting login-security state is returned (including any lockout).

The customer's login-security state after recording the event, so the integrator can surface a lockout to the end user.

eventType · enum<string> · required

The event that was recorded.

Available options: RESET_PASSWORD_COMPLETED, FAILED_LOGIN_ATTEMPT

Example:

"FAILED_LOGIN_ATTEMPT"

suspended · boolean · required

Whether the customer's login is currently suspended (locked with no automatic expiry). A suspended customer must go through a password reset (RESET_PASSWORD_COMPLETED) to clear the lockout.

failedAttempts · integer · required

The customer's current cumulative failed-login count.

Example:

5

lockedUntil · string<date-time> | null

When the customer may attempt to log in again, if temporarily locked. Null when not locked, or when suspended is true (no automatic expiry).

Example:

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