# Request API

The request API handles identity checks, document signing, enrolment and in-page sign-in. Your backend names the product it needs in `POST /v1/requests` and receives an answer immediately. If a check needs more time, it runs in the background; your backend polls for the result or waits for a callback.

The request API is separate from the legacy SSC signing and KYC APIs, both of which remain fully supported. Start new integrations with the request API unless you need one of the older paths.

---

## Authentication

Your backend authenticates with an app token, a short-lived bearer token obtained through the OAuth 2.0 client-credentials grant. Request it from the OpenID Connect (OIDC) token endpoint before making request API calls.

```
POST /auth/realms/signa/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<your-client-id>
&client_secret=<your-client-secret>
&scope=<product-scope>
```

The token authorises only the products covered by its scopes. Your application must hold the relevant scope, such as `identity_check`, `signature`, `enrolment` or `sign_in`, before it can obtain a token for that product. Contact the SecurySign team or use your dashboard to request the scopes your integration needs.

Include the token on every request API call:

```
Authorization: Bearer <app-token>
```

App tokens expire after 60 minutes. Your backend should request a new token before the current one expires.

The first request your app sends for a given product pins the app to that product's current version. All subsequent requests for that product use the pinned version. To override the version for a single call, send the `SecurySign-Version` header:

```
SecurySign-Version: identity_check=2026-10-30
```

To override several products in one header, separate the entries with commas.

---

## Making a request

```
POST /v1/requests
Authorization: Bearer <app-token>
Content-Type: application/json
```

The server returns HTTP `202` with an answer object, then starts any background check.

Send these fields in the request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `product` | string | Yes | The product to run. See [Products](#/docs/request-api-products) for the full list. |
| `idempotency_key` | string | Yes | Up to 128 printable non-space ASCII characters, unique per request. The same key with identical body is a safe retry; the same key with a different body returns `409`. |
| `subject` | object | Most products | Identifies the customer: `{"customer_id": "…"}` or `{"sub": "…"}`. Not required for `verification`, `assistant_reply` or `sign_in`. |
| `checks` | array | `identity_check` only | Subset of `["document","selfie","liveness_passive","liveness_active"]`. Omit for other products. |
| `inputs` | object | Varies | Product-specific input data such as document images or a document hash. |
| `options` | object | Varies | Product-specific options. |
| `after` | string | No | The `id` of an earlier request in the same flow, for chaining. |
| `callback_url` | string | No | An HTTPS URL that receives the completed result. |

The request body must not exceed 50 MB. Bodies larger than this are charged as refusals.

---

## The answer

Every endpoint in the request API returns an answer object with this shape:

```json
{
  "id": "req_XXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "processing",
  "product": "identity_check",
  "version": "2026-10-30",
  "subject": { "customer_id": "cust_123" },
  "checks": ["document", "selfie"],
  "result": null,
  "reasons": [],
  "action": null,
  "units_spent": 1,
  "units_left": 42,
  "after": null,
  "after_benefit": null,
  "created_at": "2026-11-18T10:00:00Z",
  "completed_at": null
}
```

The `status` field tells you what happens next:

| Status | Meaning |
|---|---|
| `processing` | The check is running. Poll with `GET /v1/requests/{id}`. |
| `action_required` | The customer must take an action. The `action` field describes the next step. |
| `needs_review` | The check reached a borderline result requiring human review. |
| `completed` | The check finished. `result` holds the outcome. |
| `failed` | The check could not complete or did not pass. `reasons` describes why. |

---

## Reading and listing requests

To read the current answer for one request:

```
GET /v1/requests/{id}
Authorization: Bearer <app-token>
```

For `identity_check` and `enrolment` requests in `action_required` status, this call also polls the underlying check and may update the status before returning.

To list your app's requests:

```
GET /v1/requests?limit=100&after=req_…
Authorization: Bearer <app-token>
```

The response lists requests newest first. `limit` accepts 1–100 (default 100). Pass the `next` field from the previous response as `after` to retrieve the next page.

---

## Idempotency

Every request requires a unique `idempotency_key`. If your backend sends the same key with the same body more than once — for example, after a network timeout — the server returns the original answer at no additional cost.

If the same key arrives with a different body, the server returns `409 idempotency_conflict`. Generate a new key for each distinct request.

---

## Chaining requests

Set `after` to the `id` of an earlier request to link the two requests into a flow. Depending on the products and the earlier result, SecurySign may reuse a completed step.

Both requests must belong to the same app and customer. The app token that created the earlier request must still be valid, or that request must have finished less than five minutes ago. If either requirement is unmet, the server returns `422`.

Sending `after` when no benefit applies records a plain link and costs nothing extra.

The following benefits let the customer skip a step:

| New product | Earlier product | Benefit | What it gives |
|---|---|---|---|
| `identity_check` | `identity_check` | `document_kept` | The earlier request failed only on the face. The document stands; send only the new selfie or ask for liveness. |
| `enrolment` | `identity_check` | `customer_proved` | The earlier request returned `verified`. The hosted enrolment page skips the selfie step; the link lives 15 minutes. |

The `after_benefit` field in every answer records the benefit that was applied, or `null` for a plain link. Call `GET /v1/products` to retrieve the full list of benefits for the products your app uses.

---

## Units and wallet

Request API usage is paid from a prepaid unit wallet. Buy units on the billing page; SecurySign deducts them as it processes requests. This usage does not draw on a monthly allowance.

- Every accepted request deducts its product's unit price from the wallet.
- Every refused request also costs 1 unit, except `401` and `402` refusals and safe retries.
- The wallet balance after each request appears in `units_left`.
- When the wallet reaches zero, further requests return `402 insufficient_units`.
- A retry with the same `idempotency_key` and identical body costs nothing.

Unit prices are set per product and per deployment. Call `GET /v1/products` to see the current price for each product your app uses. Minimum price: 1 unit; maximum: 100,000 units.

Your app can use a unit wallet and a subscription plan at the same time; they are billed separately.

---

## Callbacks

Set `callback_url` on a request to receive a notification when it reaches a terminal status (`completed`, `failed` or `needs_review`). The URL must use HTTPS and resolve to a public IP address.

The server sends an HTTP POST to `callback_url`. The body is identical to `GET /v1/requests/{id}` for that request.

Each callback includes an `X-SecurySign-Signature` header containing a JSON Web Token (JWT) signed with ES256. Its claims identify the request and delivery and bind the signature to the body:

| Claim | Description |
|---|---|
| `req` | The request id. |
| `evt` | A unique event id for this delivery. |
| `body_sha256` | Hex SHA-256 of the raw response body. |
| `iat` | Unix timestamp of the delivery. |

Verify the callback before using its result:

1. Fetch the JSON Web Key (JWK) Set from `GET /v1/callback-keys`. The endpoint requires no authentication. Cache the result; it changes rarely.
2. Match the JWT's `kid` header to a key in the set. If no key matches, refresh your cache and retry once.
3. Verify the ES256 signature against the matched public key.
4. Compute the SHA-256 of the raw HTTP request body and compare it to `body_sha256`.

If your endpoint returns a non-2xx response, the server retries at: 60 s, 300 s, 900 s, 3 600 s, 7 200 s, 14 400 s. The server gives up after 24 hours.

---

## Rate limits

All limits are per IP address per 60-second window. Exceeding a limit returns `429`.

| Bucket | Limit | Endpoints |
|---|---|---|
| `request_create` | 30/min | `POST /v1/requests` |
| `request_read` | 120/min | `GET /v1/requests/{id}`, `GET /v1/requests`, `GET /v1/products` |
| `request_write` | 30/min | `POST /v1/requests/{id}/capture`, `POST /v1/requests/{id}/inputs` |
| `sign_in_page` | 60/min | `GET /v1/sign-in/{token}`, `POST /v1/sign-in/{token}` |
| `callback_keys` | 30/min | `GET /v1/callback-keys` |
