> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vlenseg.com/llms.txt.
> For full documentation content, see https://docs.vlenseg.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vlenseg.com/_mcp/server.

# Iframe Integration

The Identity User Session API lets you embed the complete Vlens verification and contracting UX inside your own application using an iframe or WebView — without exposing your `ApiKey` or admin credentials to the client.

## How it works

1. Your **server** calls Vlens to create a session token for a specific user
2. Your server passes that token to your **client app**
3. The client loads the Vlens iframe using the session token
4. The user completes registration, KYC, and/or contract signing inside the iframe
5. Your app listens for completion events

## Session types

### Auth Session

A standard session that prompts the user through whatever steps are needed based on their current state (registration, KYC, contract signing). The user's experience is determined by `sessionPermissions`.

**Authentication:** Requires only `ApiKey` — no admin token.

```bash
curl -X POST "https://api.vlenseg.com/api/IdentityUserSession/CreateAuthSession" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+201234567890",
    "sessionPermissions": {
      "allowedContractTypeIds": [414],
      "minimalSignatureFlow": true,
      "DigitalIdentityOnly": false
    }
  }'
```

### Invitation Session

A session with pre-filled form data. Use this when you have already collected the customer's information and want to minimize the steps the user must complete.

**Authentication:** Requires admin bearer token + `ApiKey`.

```bash
curl -X POST "https://api.vlenseg.com/api/IdentityUserSession/CreateInvitation" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "SessionInput": {
      "phoneNumber": "+201234567890",
      "sessionPermissions": {
        "allowedContractTypeIds": [414],
        "minimalSignatureFlow": true,
        "DigitalIdentityOnly": false
      },
      "RequestFieldsValues": {
        "414": {
          "fullName": "Ahmed Mohamed",
          "monthlyIncome": "5000"
        }
      }
    }
  }'
```

`RequestFieldsValues` is keyed by contract type ID, then by field key. Get the field keys from `GetBusinessRequestTypeTemplateFields`.

## Session permissions

| Field                    | Type      | Description                                                |
| ------------------------ | --------- | ---------------------------------------------------------- |
| `allowedContractTypeIds` | `int[]`   | The contract type IDs the user may create in this session  |
| `minimalSignatureFlow`   | `boolean` | Skip optional steps and use the streamlined signing UX     |
| `DigitalIdentityOnly`    | `boolean` | Only perform KYC verification — skip the contracting steps |

## Loading the iframe

Both session endpoints return a session token in `data`. Pass this token when initializing the Vlens iframe or WebView:

```html
<iframe
  src="https://app.vlenseg.com/session?token=SESSION_TOKEN"
  width="100%"
  height="700"
  allow="camera; microphone"
/>
```

The `allow="camera; microphone"` attribute is required for the liveness detection step to function correctly in the browser.

## When to use each flow

| Scenario                                                               | Recommended flow                              |
| ---------------------------------------------------------------------- | --------------------------------------------- |
| You control a mobile app and want native ID capture                    | [Native API flow](/digital-identity)          |
| You want to embed Vlens in a web page with minimal integration effort  | Auth Session (iframe)                         |
| You have collected customer data server-side and want to skip the form | Invitation Session (iframe)                   |
| You want to run KYC without contracting                                | Auth Session with `DigitalIdentityOnly: true` |