> For the complete documentation index, see [llms.txt](https://docs.keyless.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keyless.io/idv-bridge/readme/idv-bridge-on-premise/keyless-agent-endpoints.md).

# Keyless Agent Endpoints

The following endpoints are available for IDV Bridge On-Premise (Keyless Agent)

**1. `GET /health-check`**

**Purpose:** Check if the service is running.\
**Response:**

```json
{
  "version": "string",
  "status": "ok"
}
```

***

**2. `POST /v1/offline-enrollment`**

**Purpose:** Generate *client* and *server* enrollment states from an image. 

The Server state is required to register the new user on the Keyless backend, while Client state enables the [account recovery](https://docs.keyless.io/consumer/mobile-sdk-use-cases/guide-account-recovery) flow for ongoing authentication on a camera enabled device via the Mobile SDK.

\
**Request:**

* **Headers:**
  * `Exif-Transpose` *(boolean, optional)* — whether to rotate the image according to EXIF metadata.
  * `Content-Encoding` *(optional, const="base64")* — if the image is base64 encoded.
  * `Scenario` *(required)* — `"SELFIE" | "TRUSTED_SOURCE" | "DOCUMENT"`.
* **Body:** `image/*` — binary (JPEG, PNG, BMP, etc.)

**Responses:**

* `200`: Returns **OfflineEnrollment**
* `422`: Returns **FilterTriggered**
* `429`: Too many concurrent enrollments

`scenario` definitions are available [here](https://docs.keyless.io/idv-bridge/readme/idv-bridge-saas#scenarios).

***

**3. `POST /v1/online-enrollment`**

**Purpose:** Enroll a user directly from an image (without server state).

Client state enables the [account recovery](https://docs.keyless.io/consumer/mobile-sdk-use-cases/guide-account-recovery) flow for ongoing authentication on a camera enabled device via the Mobile SDK.

\
**Request:** Same headers/body as offline enrollment.\
**Responses:**

* `200`: Returns **OnlineEnrollment**
* `409`: Not configured for online enrollment
* `422`: Recognition filter error
* `429`: Too many concurrent enrollments

***

### Schemas

`OfflineEnrollment`

<table><thead><tr><th width="171.69549560546875">Field</th><th width="130.1904296875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>keylessId</code></td><td>string</td><td>Unique user ID</td></tr><tr><td><code>clientState</code></td><td>string</td><td>Opaque data for the Keyless SDK to allow a user to authenticate on a camera enabled device for the accoutn recovery flow.</td></tr><tr><td><code>serverState</code></td><td>string</td><td>Uncommitted server data; required to register the new user on the Keyless backend. </td></tr></tbody></table>

`OnlineEnrollment`

<table><thead><tr><th width="172.57537841796875">Field</th><th width="126.6259765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>keylessId</code></td><td>string</td><td>Unique user ID</td></tr><tr><td><code>clientState</code></td><td>string</td><td>Opaque data for the Keyless SDK to allow a user to authenticate on a camera enabled device for the accoutn recovery flow.</td></tr></tbody></table>

`FilterTriggered`&#x20;

<table><thead><tr><th width="164.327392578125">Field</th><th width="139.609130859375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>title</code></td><td>string</td><td>Always <code>"Filter Triggered"</code></td></tr><tr><td><code>statusCode</code></td><td>integer</td><td>Always <code>422</code></td></tr><tr><td><code>detail</code></td><td>string</td><td>Explanation of why the filters failed</td></tr><tr><td><code>filters</code></td><td>object</td><td>See below</td></tr></tbody></table>

**`Filters`**

Each property represents a possible filter and has a status:

* `TRIGGERED` – filter was triggered (failure)
* `NOT_TRIGGERED` – filter passed
* `TURNED_OFF` – filter not active
* `CANNOT_RUN_ON_FRAME` – preprocessing failure

**Filter fields:**

<table><thead><tr><th width="212.60906982421875">Filters</th><th>Description</th></tr></thead><tbody><tr><td><code>faceIsOccluded</code></td><td>The facial features are in part covered by something to the extent that a biometric template could not be detected.</td></tr><tr><td><code>faceMissing</code></td><td>No face was detected in the image.</td></tr><tr><td><code>faceMultiple</code></td><td>More than one face was detected.</td></tr><tr><td><code>facePartial</code></td><td>Only a partial face was detected, for example the selfie may have been off-center.</td></tr><tr><td><code>faceTooSmall</code></td><td>A face was detected, but the face was too small to allow an accurate biometric template to be generated.</td></tr><tr><td><code>imageBlackAndWhite</code></td><td>The image is black and white.</td></tr></tbody></table>

#### Example 422 Error

```json
{
  "title": "Filter Triggered",
  "statusCode": 422,
  "detail": "Face occluded by object",
  "filters": {
    "faceIsOccluded": "TRIGGERED",
    "faceMissing": "NOT_TRIGGERED",
    "faceMultiple": "NOT_TRIGGERED",
    "facePartial": "NOT_TRIGGERED",
    "faceTooSmall": "NOT_TRIGGERED",
    "imageBlackAndWhite": "NOT_TRIGGERED"
  }
}

```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.keyless.io/idv-bridge/readme/idv-bridge-on-premise/keyless-agent-endpoints.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.