# Products

A product tells SecurySign what work to do: check an identity, sign a document or enrol a customer, for example. Your backend selects it in `POST /v1/requests`. Call `GET /v1/products` to see the current version, unit price and chaining benefits for each product available to your app.

The first request for a product pins your app to its current version. Later requests keep using that version unless you send a `SecurySign-Version` header to override it for one call.

---

## identity-check

The `identity_check` product checks a customer's identity document through SecurySign's document engine and returns a verdict. The check can also include a selfie or a liveness check.

Choose from `document`, `selfie`, `liveness_passive` and `liveness_active` in the `checks` array. Include at least `document`.

**inputs:**

| Field | Type | Required | Description |
|---|---|---|---|
| `inputs.document.images` | array of strings | No | Base64-encoded JPEG or PNG images of the document. Send the front first, then the back for national identity cards. Omit when the document already passed on a previous request and you are retrying only the face step. |
| `inputs.selfie` | string | No | A single base64-encoded photo of the customer's face. When present, SecurySign's liveness component compares the selfie against the document portrait after document processing. |

**options:**

| Field | Type | Required | Description |
|---|---|---|---|
| `options.phone_number` | string | Conditional | Required when `customer_id` is not itself a phone number. International format: `+CCNNN…`. |
| `options.fallback` | any truthy value | No | When present, a selfie that cannot be used falls back to liveness rather than failing the request outright. |

The next step depends on the inputs you send and the checks you request:

1. If you supply document images and an optional selfie in `inputs`, SecurySign processes them. The status starts at `processing` and transitions to `completed` or `failed` after the check runs.

2. If you supply no inputs, the request returns immediately with `status: action_required`. The `action` object contains a `url` (the hosted capture page) and `expires_at`. The customer opens the link; calling `GET /v1/requests/{id}` after the customer completes the step returns the updated status.

3. If you requested liveness without supplying a selfie, once the document passes, the request stays in `action_required` with `action.url`, `action.capture_session_url` and `action.inputs_url`.

When the request is in `action_required` for liveness, complete the capture as follows:

1. Call `POST /v1/requests/{id}/capture`. The response contains `url`, `token`, `liveness_type` (`passive` or `active`) and `expires_at`.
2. Load SecurySign's liveness component in your frontend using the returned `url` and `token`.
3. When the component finishes, submit the transaction with `POST /v1/requests/{id}/inputs`:
   ```json
   { "liveness_transaction_id": "<transaction-id-from-the-component>" }
   ```
4. Poll `GET /v1/requests/{id}` for the final result.

`/capture` returns `409 not_waiting` if the request is not waiting for a capture. A `422 capture_unavailable` means the liveness engine could not create a session; try again.

`/inputs` can also return `409 not_waiting`. A `422 invalid_input` means `liveness_transaction_id` is missing or malformed. For `422 capture_refused`, the liveness engine rejected the transaction; call `/capture` again.

**result** (when `completed`):

```json
{
  "outcome": "verified | document_verified | face_mismatch | not_genuine | identity_mismatch | selfie_unreadable | document_unreadable | could_not_complete",
  "assurance": {
    "level": "LOA-1 | LOA-2 | LOA-3 | LOA-4",
    "proven_by": "securysign_record"
  },
  "document": {
    "doc_type": "…",
    "verified_name": "…",
    "doc_expiry": "…"
  }
}
```

The assurance level reflects the checks that passed: `document` only gives LOA-1; adding `selfie` gives LOA-2; `liveness_passive` gives LOA-3; `liveness_active` gives LOA-4.

**reasons** (when `failed`): `document_not_authentic`, `face_mismatch`, `identity_mismatch`, `liveness_failed`, `selfie_unreadable`, `document_unreadable`, `could_not_complete`.

A later request can reuse a step from this identity check:

| To product | Benefit | Condition | What the new request receives |
|---|---|---|---|
| `identity_check` | `document_kept` | The earlier check failed only on the face step | The document stands; send only a new selfie or ask for liveness |
| `enrolment` | `customer_proved` | The earlier check returned `verified` | The hosted enrolment page skips the selfie step; the link lives 15 minutes |

---

## sign-in

The `sign_in` product creates a one-time link for the identity frame. Embed it in an `<iframe>` on your app's own page so the customer can sign in with a passkey. The request completes when they sign in or the link expires.

No subject is required. To restrict sign-in to one account, pass `options.sub`.

**options:**

| Field | Type | Required | Description |
|---|---|---|---|
| `options.redirect_uri` | string | No | One of your app's registered redirect URIs. Defaults to the first registered URI. |
| `options.state` | string | No | Up to 255 printable ASCII characters. Returned verbatim in `SIDV_RESULT.state` from the frame. |
| `options.sub` | string | No | When present, only the account with this `sub` may sign in. |

The sign-in link is valid for 600 seconds. After that, the request moves to `failed` with the reason: "The person didn't sign in within 10 minutes."

**action** (returned immediately):

```json
{
  "frame_url": "https://securysign.com/#/id-frame?t=<one-time-token>",
  "expires_at": "2026-11-18T12:10:00Z"
}
```

Your backend sends `frame_url` to your frontend, which loads it in an `<iframe>` on the app's own page. The frame sends `SIDV_*` messages to the parent window. See the [Iframe](#/docs/iframe) page for the full message reference.

The frame must be embedded inside the app's own page. A direct navigation to the frame URL returns `403`.

**result** (when `completed`):

```json
{
  "outcome": "signed_in",
  "sub": "the-signer's-sub",
  "auth_time": "2026-11-18T12:05:00Z",
  "method": "passkey",
  "customer": "customer_id-if-enrolled"
}
```

`customer` is present only when the signed-in account has an active SecurySign certificate.

---

## enrolment

The `enrolment` product creates a link to the hosted enrolment page, where the customer registers a passkey and receives a certificate. The request completes when the enrolment page closes.

**options:**

| Field | Type | Required | Description |
|---|---|---|---|
| `options.redirect_uri` | string | No | A redirect URI registered on your app. The enrolment page redirects the customer here after completion. |

**action** (returned immediately):

```json
{
  "url": "https://securysign.com/enrol?t=…",
  "expires_at": "2026-11-18T13:00:00Z"
}
```

Your app sends `action.url` to the customer. The customer opens it; the enrolment page handles identity proofing and passkey registration.

If `after` names an `identity_check` that returned `verified`, the request receives the `customer_proved` benefit: the hosted enrolment page skips the selfie step because the customer has already proved their identity. With this benefit, the link expires after 15 minutes rather than its standard expiry.

Before accepting the request, SecurySign checks that the wallet can cover both the enrolment unit and the certificate unit. If the wallet cannot cover both, the request returns `402 insufficient_units`.

---

## signature

The `signature` product asks the customer to approve a document hash with a passkey. It returns a signing frame for your app to embed. Once the customer approves, the request completes with the signed result.

**inputs:**

| Field | Type | Required | Description |
|---|---|---|---|
| `inputs.document_hash` | string | Yes | Hex-encoded SHA-256 hash of the document to sign. |
| `inputs.document_name` | string | Yes | The document filename shown to the customer in the signing frame. |

**options:**

| Field | Type | Required | Description |
|---|---|---|---|
| `options.approval` | string | No | `passkey` (default) or `ussd` where configured. |

**action** (when `action_required`):

The `action` object contains a signing frame URL. Load that URL in an `<iframe>` on your page. The SSC frame sends `SSC_*` messages when the customer signs or cancels. See the [Iframe](#/docs/iframe) page for the full message reference.

When the request is `completed`, `result` contains the signature bytes and signing metadata.

Signing through this product uses a prepaid unit and bypasses the app's monthly signing limit.

---

## visible-signature

The `visible_signature` product works like `signature`: the customer approves with a passkey. Its signed result also includes a handwriting image that SecurySign renders as a visible stamp on the document. See the [Iframe](#/docs/iframe) page for the signing frame messages.

---

## verification

The `verification` product checks a document signature against the SecurySign certificate store and returns the result. No `subject` is required.

---

## certificate

The `certificate` product issues or renews a customer's signing certificate. The certificate is linked to the customer's enrolled passkey. Use this product when the customer's certificate has expired or been revoked before requesting a signature.

---

## certificate-revocation

The `certificate_revocation` product revokes the customer's current signing certificate. The customer's passkey remains registered; a new certificate may be issued with the `certificate` product.

---

## encryption

The `encryption` product encrypts a payload using the customer's certificate public key. The encrypted result can only be decrypted by the holder of the matching private key.

---

## allocation

The `allocation` product reserves a unit of capacity for a customer ahead of a later operation. Use it when the billing decision needs to happen separately from the operation.

---

## assistant-reply

The `assistant_reply` product generates an AI-assisted help or support reply for applications that embed SecurySign's assistant. No `subject` is required.
