API authentication

All integration endpoint requests must include:

Header	Required	Description
`X-API-Key`	Yes	Your client API Key
`Content-Type`	Yes (when body present)	`application/json`

Integration routes authenticate with API Key only; no API Secret is required.

Invalid credentials

If the API Key is missing or invalid, the API returns 401 Unauthorized:

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing X-API-Key header"
}

Possible messages: "Missing X-API-Key header", "Invalid API key".

Suspended or inactive client

If your client is suspended or in onboarding, you will receive 403 Forbidden with details in the detail field. Scoring routes (POST /score, POST /score/batch) require fraud_detection_consent=true configured for your client in Kairo Connect.

There is no consent header for you to send.
If consent was not granted, scoring returns 403 with: "Fraud detection consent not granted for this client."

Rate limiting

Kairo Shield applies a per-minute request limit per API Key (configurable per client). Responses include:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window (60 s)
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Seconds until the window resets

If you exceed the limit, you receive 429 Too Many Requests with header Retry-After: 60.

Kairo Connect

Kairo Shield — Introduction

Kairo Shield — Getting started

Kairo Shield — API

Kairo Shield — Reference

Kairo Shield — Webhooks

Kairo Shield — Summary

Invalid credentials

Suspended or inactive client

Rate limiting

​Invalid credentials

​Suspended or inactive client

​Fraud detection consent (Ley 1581)

​Rate limiting

Invalid credentials

Suspended or inactive client

Fraud detection consent (Ley 1581)

Rate limiting