Products

User Profile

Login, token refresh, and account management — email, phone, and password

View as Markdown

This page covers all user-facing account management flows: login (with OTP), token refresh, email and phone updates, password change, and password reset.

Registration paths

Vlens has two separate registration flows. Choose one per user based on CheckExistenceOfEmailOrPhone:

FlowWhen to useUser-facing stepsDocumented in
StandardhasCDI is false or absent — new user8 — phone OTP (send + enter), email OTP (send + enter), account, ID front, ID back, livenessThis page → Standard registration flow
CDIhasCDI: true — network identity eligible for consent-based reuse2 — phone OTP (consent), livenessConsent-based Digital Identity (CDI)

Do not combine steps from both flows (for example, do not call verify/id/front after a CDI StepCreate).

Standard registration flow

Phone OTP → optional email OTP → StepCreate → then ID scan and liveness on the Digital Identity page. Login only repeats the phone OTP step afterward.

This diagram is the standard path only. If CheckExistenceOfEmailOrPhone returns hasCDI: true, stop here and follow Consent-based Digital Identity (CDI) instead — no verify/* steps afterward.

After standard registration, login does not repeat the ID or liveness steps. The user only enters phone + password and validates the SMS OTP.

Login

Login calls the same endpoint twice — first to trigger the OTP SMS, then to validate it and receive tokens.

Step 1 — Submit credentials (triggers SMS OTP)

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/Login" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "geoLocation": { "latitude": 30.0444, "longitude": 31.2357 },
>    "imei": "DEVICE_ID",
>    "phoneNumber": "+201234567890",
>    "password": "USER_PASSWORD",
>    "smsProviders": 0
>  }'

Save data.phoneNumberOtpRequestId from the response.

Step 2 — Validate OTP and receive tokens

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/Login" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "geoLocation": { "latitude": 30.0444, "longitude": 31.2357 },
>    "imei": "DEVICE_ID",
>    "phoneNumber": "+201234567890",
>    "password": "USER_PASSWORD",
>    "smsProviders": 0,
>    "phoneNumberOtpRequestId": "OTP_REQUEST_ID",
>    "phoneNumberOtp": "123456"
>  }'

Response:

1{
2  "data": {
3    "accessToken": "eyJ...",
4    "refreshToken": "eyJ...",
5    "expireInSeconds": 86400,
6    "isDigitalIdentityVerified": true,
7    "hasPendingRequest": false,
8    "user": {
9      "fullName": "Ahmed Mohamed",
10      "phoneNumber": "+201234567890",
11      "idNumber": "29901234567890"
12    }
13  },
14  "error_code": null
15}

smsProviders values: 0 = default, 1 = Infobip, 2 = Vodafone, 3 = Cequens, 4 = Victory Link, 5 = BroadNet, 6 = Ezagel, 7 = Orange.

When you do not want to build a registration or login UI, generate a signed Vlens web URL server-side and redirect the user to it. This is a browser redirect flow — not the same as Iframe Integration and not related to linking a pre-login transaction.

EndpointPurpose
POST /api/DigitalIdentity/GenerateRegisterLinkHosted registration flow
POST /api/DigitalIdentity/GenerateLoginLinkHosted login flow

Both accept optional phoneNumber, email, latitude, longitude, imei, and returnUrl. The response data field is the URL to open in a browser.

$curl -X POST https://api.vlenseg.com/api/DigitalIdentity/GenerateRegisterLink \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "phoneNumber": "+201234567890",
>    "returnUrl": "https://yourapp.com/registration-complete"
>  }'

Refresh token

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/RefreshToken" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer CURRENT_ACCESS_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{"refreshToken": "YOUR_REFRESH_TOKEN"}'

Both return data.accessToken and data.refreshToken.

Log out

Invalidate the current user session. Requires ApiKey and a user bearer token.

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/Logout" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer USER_TOKEN"

Update email

Step 1 — Request email OTP

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/UpdateEmailRequest" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer USER_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{"email": "new@example.com"}'

Save data.emailOtpRequestId from the response.

Step 2 — Validate OTP

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/ValidateUpdateEmailRequestOtp" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer USER_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "emailOtpRequestId": "OTP_REQUEST_ID",
>    "emailOtp": "123456"
>  }'

Verify email (post-registration)

If email verification was skipped during registration (skipEmail: true), the user can verify later.

Step 1 — Request email OTP

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/VerifyEmail" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer USER_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{"email": "user@example.com"}'

Save data.emailOtpRequestId.

Step 2 — Validate OTP

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/VerifyEmail" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer USER_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "email": "user@example.com",
>    "emailOtpRequestId": "OTP_REQUEST_ID",
>    "emailOtp": "123456"
>  }'

Update phone number

Changing a phone number requires liveness re-validation before the OTP is sent.

Step 1 — Send OTP to new number

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/UpdatePhone/SendPhoneOtp" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer USER_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "phoneNumber": "+201234567891",
>    "password": "USER_PASSWORD",
>    "smsProviders": 0
>  }'

Save data.phoneNumberOtpRequestId.

Step 2 — Re-validate liveness (if required)

If the response indicates liveness re-validation is needed:

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/UpdatePhone/ReValidateLiveness" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer USER_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "phoneNumber": "+201234567891",
>    "password": "USER_PASSWORD",
>    "image": "BASE64_FACE_IMAGE"
>  }'

Save the new data.phoneNumberOtpRequestId from this response.

Step 3 — Validate OTP

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/UpdatePhone/ValidatePhoneOtp" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer USER_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "phoneNumberOtpRequestId": "OTP_REQUEST_ID",
>    "phoneNumberOtp": "123456"
>  }'

Change password

Changing the current password sends an OTP to the registered email to confirm the change.

Step 1 — Request password change

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/ChangePasswordRequest" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer USER_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "currentPassword": "CURRENT_PASSWORD",
>    "newPassword": "NEW_PASSWORD"
>  }'

Save data.emailOtpRequestId.

Step 2 — Validate OTP and confirm change

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/ValidateChangePasswordRequest" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer USER_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "currentPassword": "CURRENT_PASSWORD",
>    "newPassword": "NEW_PASSWORD",
>    "emailOtpRequestId": "OTP_REQUEST_ID",
>    "emailOtp": "123456"
>  }'

Reset password

V2 variants (SendEmailOtpV2, ValidateEmailOtpV2, ValidatePhoneOtpV2, ResetV2) follow the same steps with updated validation rules.

Via email + phone (4 steps)

Step 1 — Send OTP to email

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/ForgetPassword/SendEmailOtp" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "emailOrPhoneNumber": "+201234567890",
>    "idNumber": ""
>  }'

Save data.emailOtpRequestId.

Step 2 — Validate email OTP (triggers phone OTP)

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/ForgetPassword/ValidateEmailOtp" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "emailOrPhoneNumber": "+201234567890",
>    "idNumber": "",
>    "emailOtpRequestId": "EMAIL_OTP_REQUEST_ID",
>    "emailOtp": "123456",
>    "smsProviders": 0
>  }'

Save data.phoneNumberOtpRequestId.

Step 3 — Validate phone OTP

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/ForgetPassword/ValidatePhoneOtp" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "emailOrPhoneNumber": "+201234567890",
>    "idNumber": "",
>    "phoneNumberOtpRequestId": "PHONE_OTP_REQUEST_ID",
>    "phoneNumberOtp": "123456"
>  }'

Save data.userId and data.passwordResetCode.

Step 4 — Set new password

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/ForgetPassword/Reset" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "userId": 12345,
>    "resetCode": "RESET_CODE",
>    "password": "NEW_PASSWORD"
>  }'

Via phone only (3 steps)

Step 1 — Send OTP to phone

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/ForgetPasswordByPhone/SendPhoneOtp" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"phoneNumber": "+201234567890"}'

Save data.phoneNumberOtpRequestId.

Step 2 — Validate phone OTP

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/ForgetPasswordByPhone/ValidatePhoneOtp" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "phoneNumber": "+201234567890",
>    "phoneNumberOtpRequestId": "OTP_REQUEST_ID",
>    "phoneNumberOtp": "123456"
>  }'

Save data.userId and data.passwordResetCode.

Step 3 — Set new password

$curl -X POST "https://api.vlenseg.com/api/DigitalIdentity/ForgetPasswordByPhone/Reset" \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "userId": 12345,
>    "resetCode": "RESET_CODE",
>    "password": "NEW_PASSWORD"
>  }'