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.

Sessions are device-bound and user-bound. Each session is tied to a single device (via RSA public key) and expires after 30 minutes. A device is identified by its public key — store generated key pairs securely to avoid repeated mobile verification at each login.

How it works

1. Your server calls Vlens with the user’s phone/email and session config
2. The server passes sessionStartingPath to the client app
3. The client loads the Vlens iframe at <tenancy_name>-onboarding.vlenseg.com/<sessionStartingPath>
4. The user completes registration, KYC, and/or contract signing
5. Your app receives completion events via postMessage

Create Auth Session

A session that guides the user through whatever steps are needed based on their current state. Requires only ApiKey — no admin token.

$
curl -X POST "https://api.vlenseg.com/api/IdentityUserSession/CreateAuthSession" \
>
  -H "ApiKey: YOUR_API_KEY" \
>
  -H "TenancyName: YOUR_TENANT" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "UserPublicKey": "DEVICE_RSA_PUBLIC_KEY",
>
    "PhoneNumber": "+201234567890",
>
    "Email": "user@example.com",
>
    "Language": "AR",
>
    "redirectUrl": "https://your-app.com/done",
>
    "sessionPermissions": {
>
      "allowedContractTypeIds": [414],
>
      "minimalSignatureFlow": true,
>
      "DigitalIdentityOnly": false,
>
      "SendInvitationsForCosigners": false
>
    },
>
    "CustomerSigners": [
>
      {
>
        "customerSignerIdentifier": "+201234567891",
>
        "shouldSign": true,
>
        "signOrder": 0
>
      }
>
    ],
>
    "RequestFieldsValues": {
>
      "414": {
>
        "fullName": "Ahmed Mohamed",
>
        "monthlyIncome": "5000"
>
      }
>
    }
>
  }'

Request fields

Response

1
{
2
  "data": {
3
    "sessionId": "af72ed47-7db3-40e6-acbd-e6efe01ca849",
4
    "sessionEnd": "2026-05-05T13:55:14.7043492Z",
5
    "sessionStartingPath": "/session/start?token=...",
6
    "sessionPermissions": { "..." },
7
    "redirectUrl": null,
8
    "sessionAllowedTypesSignedContracts": {
9
      "allTypesSigned": false,
10
      "signedContracts": [
11
        {
12
          "id": "4325a38b-02f7-4437-a3da-6526cb33711c",
13
          "typeId": 201,
14
          "status": "CustomerSigned",
15
          "statusId": 4
16
        }
17
      ]
18
    }
19
  },
20
  "error_code": null
21
}

sessionStartingPath is the path to append to your tenant’s base URL. If null, no session was created.

Create Invitation Session

A session with pre-filled data and an invitation notification (SMS or email) sent to the user. Requires admin bearer token + ApiKey.

Use this when you have already collected the customer’s information and want to minimize the steps they must complete.

$
curl -X POST "https://api.vlenseg.com/api/IdentityUserSession/CreateInvitation" \
>
  -H "ApiKey: YOUR_API_KEY" \
>
  -H "TenancyName: YOUR_TENANT" \
>
  -H "Authorization: Bearer ADMIN_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "sessionInput": {
>
      "UserPublicKey": "DEVICE_RSA_PUBLIC_KEY",
>
      "PhoneNumber": "+201234567890",
>
      "Language": "AR",
>
      "sessionPermissions": {
>
        "allowedContractTypeIds": [414],
>
        "minimalSignatureFlow": true,
>
        "DigitalIdentityOnly": false
>
      },
>
      "RequestFieldsValues": {
>
        "414": {
>
          "fullName": "Ahmed Mohamed",
>
          "monthlyIncome": "5000"
>
        }
>
      }
>
    },
>
    "smsProvider": 0
>
  }'

smsProvider controls which SMS gateway sends the invitation. 0 = default from tenant settings.

Invitation links are short-lived (10 minutes) but the session itself lasts 30 minutes from when the user opens it. The link acts as a one-time OTP:

• Sent via SMS → no mobile verification required at login or registration
• Sent via email → no email verification required at registration

Loading the iframe

Concatenate sessionStartingPath to your tenant’s base URL:

https://<tenancy_name>-onboarding.vlenseg.com<sessionStartingPath>

1
<iframe
2
  src="https://YOUR_TENANT-onboarding.vlenseg.com/session/start?token=..."
3
  width="100%"
4
  height="700"
5
  allow="camera; microphone"
6
/>

postMessage integration

The iframe communicates with the parent app via window.postMessage. This is required for device-bound signing — the parent app holds the private key.

Iframe → Parent (signing request):

1
window.postMessage({
2
  type: "NATIVE_CALL",
3
  method: "signContent",
4
  requestId: "123",
5
  args: { signingBody: "..." }
6
}, "*");

Parent → Iframe (signing response):

1
window.postMessage({
2
  type: "NATIVE_RESPONSE",
3
  requestId: "123",
4
  success: true,
5
  result: "signed-value",
6
  source: "native"
7
}, "*");

Key storage

The private key must never leave the device. Store it using each platform’s secure enclave:

Security features

Every session request includes three layers of protection:

Session permissions reference

Web app (no-code access)

Users can access the Vlens web app directly at:

https://<tenancy_name>-onboarding.vlenseg.com

No developer configuration is required. The web app manages keys and sessions securely — each browser is treated as a separate device with its own key pair.

To restrict access to invited users only, enable Invitation Only in the portal under Feature Control → Main Feature.

When to use each flow

Session API endpoints

Your server creates the session with CreateAuthSession or CreateInvitation. The embedded iframe then calls the endpoints below (you do not call these directly from your backend in most integrations).

For the native API equivalents (outside the iframe), see Digital Identity and E-Contracting. To associate a pre-login OCR transaction with a user after native login, see Link an existing transaction — that flow does not apply inside an iframe session.