# Developer guide
[Identomat](https://www.identomat.com/) is a service designed to verify **human identity** and **liveness** over the Internet. This guide assumes that the integrating organization (hereafter referred to as *"the company"*) operates a web server (referred to as *"the company server"*) at `example.com` and possesses a `company_key`. The `company_key` is a credential used to securely communicate between the company server and the Identomat server (`widget.identomat.com`).
For enhanced security, companies can optionally implement **HMAC authorization**. In this case, a `secret_key` is used to generate and validate HMAC signatures for secure communication.
## Procedure
The integration procedure consists of three main steps:
{% stepper %}
{% step %}
[**Acquiring a `session_token`.**](#acquiring-a-session-token)
{% endstep %}
{% step %}
[**Redirecting the user's browser to `widget.identomat.com`.**](#redirecting-to-the-identomat-widget)
{% endstep %}
{% step %}
[**Checking for a result.**](#checking-for-a-result)
{% endstep %}
{% endstepper %}
### **Acquiring a session token**
To acquire a `session_token`, your backend must send a request to the `/begin/` endpoint with the following parameters:
* `company_key` – Your unique company identifier.
* `flags` – A JSON object defining global settings for the verification session.
* `steps` – An array specifying the steps to include in the verification flow. Each step can have its own step-specific flags.
> ⚠️ The `session_token` is valid for **15 minutes** by default.
**Endpoint:**
```nginx
POST https://widget.identomat.com/begin/
```
Requests can be sent as:
* **URL query parameters**
* **URL-encoded form data**
* **JSON object** in the request body (recommended)
#### **Steps and Flags Structure**
* `flags` : Defines global behavior for the entire session.
* `steps` : Allows full control of the verification process, enabling you to specify **which steps to include** (e.g., `liveness`, `identity-document`) and configure **step-specific flags**, such as `"allow_face_upload": true` for the `liveness` step.
{% hint style="info" %}
To ensure compatibility between the old and new methods, both of which need to work together, you should use the `'skip_face'` and `'skip_document'` flags when using steps.
These flags prevent the 'identity-document' and 'liveness' steps from being duplicated if they already exist in the flow.
{% endhint %}
**Using Configuration or custom steps**
You can initiate a session in two ways:
* **Via predefined configuration (Recommended):**
* We strongly recommend using **predefined configurations** via the `config_id` parameter. Configurations ensure consistency, simplify integration, and reduce the risk of errors. Using configurations also allows us to deprecate legacy custom step handling in the future, helping clients maintain a clean and stable integration.
* **Via custom steps and flags**:\
Only use custom steps and flags if you have very specific needs that cannot be satisfied with configurations. Over time, we encourage migrating all custom flows to configurations.
{% hint style="warning" %}
**Why configurations matter:**
* **Simplifies session creation** — no need to manually define steps and flags.
* **Reduces risk of errors** in the verification flow.
* **Future-proof** — legacy custom step handling will eventually be deprecated.
* Enables Identomat to **maintain**, **improve**, and **optimize** **flows** efficiently.
* Makes **integration** easier.
{% endhint %}
{% hint style="info" %}
📘 For detailed parameter definitions and examples, refer to the [**API Reference.**](/developer-tools/api-reference.md#begin-session-creation)
{% endhint %}
### Redirecting to the Identomat Widget
To start a verification session, the company server must redirect the user’s browser to:
```
https://widget.identomat.com/?session_token={session_token_here}
```
Replace `{session_token_here}` with the actual token received from the `/begin/` endpoint.
### Embedding in an Iframe
Alternatively, the widget can be embedded within an iframe:
```html
```
> ⚠️ The `allow="camera"` attribute is required to grant camera access.
### **Checking for a result**
Once the verification process is completed, the result can be detected in two ways depending on how the widget was integrated:
* **If** **redirected**\
If you used a redirect approach (not embedded in an iframe), the user will be redirected to the `return_url` specified in the configuration or session flags, with the `session_token` appended as a query parameter.
```
https://yourapp.com/?session_token=abc123xyz
```
* **If embedded in an iframe**, the process completion can be detected using JavaScript:
```javascript
addEventListener('message', function (e) {
if (e.origin !== 'https://widget.identomat.com') return;
if (e.data !== 'DONE') return;
// Process completed, handle results here
});
```
> ✅ Ensure you verify the message `origin` to avoid security risks.
***
## Quick links
Access detailed developer guides for **KYC (Know Your Customer)** and **KYB (Know Your Business)** flows. Click a card below to explore configuration, integration steps, and best practices for each verification type.
KYC (Know Your Customer)
Learn how to collect and verify individual user data, configure verification steps, and integrate KYC flows.
---
# Agent Instructions: 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:
```
GET https://docs.identomat.com/developer-tools/developer-guide.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.