Record a security event

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

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

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  \"endUserIpAddress\": \"203.0.113.42\"\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()

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

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

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

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

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

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

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

POST

sca

record-event

Record a security event

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

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

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  \"endUserIpAddress\": \"203.0.113.42\"\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()

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

{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

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

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

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

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

{
  "status": 500,
  "code": "GRID_SWITCH_ERROR",
  "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"

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

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"

Using the API

API documentation

Record a security event

Authorizations

Query Parameters

Body

Response