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

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

fetch('https://api.lightspark.com/grid/2025-10-13/sca/record-event', 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  \"eventType\": \"FAILED_LOGIN_ATTEMPT\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/sca/record-event")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

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

200

{
  "eventType": "FAILED_LOGIN_ATTEMPT",
  "suspended": true,
  "failedAttempts": 5,
  "lockedUntil": "2025-10-03T12:15:00Z"
}

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

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

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

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

{
  "status": 423,
  "code": "ACCOUNT_LOCKED",
  "message": "<string>",
  "details": {
    "suspended": true,
    "lockedUntil": "2023-11-07T05:31:56Z",
    "failedAttempts": 123
  }
}

{
  "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 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"

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"