API basics

Authentication

API keys, bearer tokens, and the dual-auth model

View as Markdown

Every Vlens API request requires two credentials:

HeaderValueRequired on
ApiKeyStatic key assigned to your tenantEvery request
AuthorizationBearer <token>Every request (token type depends on the caller)

Token types

Admin token

Used for service-to-service calls and management operations. Obtained by calling /api/credentials/Login with your admin credentials.

$curl -X POST https://api.vlenseg.com/api/credentials/Login \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "TenancyName: YOUR_TENANT" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "tenancyName": "YOUR_TENANT",
>    "userNameOrEmailAddress": "admin@yourtenant.com",
>    "password": "YOUR_PASSWORD"
>  }'

Response:

1{
2  "data": {
3    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
4    "expireInSeconds": 86400,
5    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
6    "refreshTokenExpireInSeconds": 604800
7  }
8}

Lifetime: 24 hours. Use the refreshToken to get a new access token before it expires.

User token

Returned by the registration and login flows. Used for all user-scoped operations (identity verification, business request creation, contract signing).

User tokens are returned in the data.accessToken field of /api/DigitalIdentity/Register and other user-facing endpoints.

User token via OAuth (Google / Microsoft)

Users can authenticate using an existing Google or Microsoft account. The OAuth token from the provider is verified by Vlens, and the resulting oAuthTokenVerificationRequestId is passed to /Register to skip the email verification step.

$# 1 — Verify the OAuth token
$curl -X POST https://api.vlenseg.com/api/DigitalIdentity/Register/StepVerifyOAuthToken \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "provider": "Google",
>    "IdToken": "OAUTH_ID_TOKEN_FROM_PROVIDER"
>  }'
$
$# 2 — Complete registration using the oAuthTokenVerificationRequestId
$curl -X POST https://api.vlenseg.com/api/DigitalIdentity/Register \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "phoneNumber": "+201234567890",
>    "oAuthTokenVerificationRequestId": "GUID_FROM_STEP_1"
>  }'

OAuth provider setup is configured in the Vlens portal. See the Google Cloud Platform Console and Azure AD B2C documentation for creating OAuth client credentials.

API-key-only (public endpoints)

Some endpoints require only the ApiKey header and no bearer token. These are public registration endpoints:

  • POST /api/DigitalIdentity/CheckExistenceOfEmailOrPhone
  • POST /api/DigitalIdentity/Register/StepVerifyPhone
  • POST /api/DigitalIdentity/Register/StepVerifyEmail
  • POST /api/DigitalIdentity/Register/StepVerifyOAuthToken
  • POST /api/DigitalIdentity/VerifyOAuthToken
  • POST /api/DigitalIdentity/Register
  • POST /api/DigitalIdentity/Register/StepCreate
  • POST /api/DigitalIdentity/GenerateRegisterLink
  • POST /api/DigitalIdentity/GenerateLoginLink
  • POST /api/DigitalIdentity/RefreshToken
  • POST /api/DigitalIdentity/ForgetPassword/SendEmailOtp
  • POST /api/DigitalIdentity/ForgetPassword/SendEmailOtpV2
  • POST /api/DigitalIdentity/ForgetPasswordByPhone/SendPhoneOtp
  • POST /api/IdentityUserSession/CreateAuthSession

Refreshing tokens

Admin token

Use the refresh token from /api/credentials/Login to get a new admin access token without re-authenticating. Refresh tokens expire after 7 days.

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

User token

User refresh and logout flows are documented in User Profile.

Rotate refresh tokens server-side and never expose them in client-side code or mobile apps.

Request headers

A complete request with both credentials looks like this:

$curl -X POST https://api.vlenseg.com/api/DigitalIdentity/verify/id/front \
>  -H "ApiKey: YOUR_API_KEY" \
>  -H "Authorization: Bearer USER_ACCESS_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{"image": "BASE64_IMAGE"}'

Multi-tenant context

Vlens is multi-tenant. Your ApiKey is scoped to your tenant — you cannot access another tenant’s data. Admin tokens issued by /api/credentials/Login are also tenant-scoped.

When using the admin login endpoint, pass your TenancyName in both the request body (tenancyName field) and as a header.

Security best practices

  • Store ApiKey and admin credentials server-side only — never in client-side code or mobile apps.
  • For mobile apps, use one of the native SDKs (Android, iOS, Flutter, React Native) — they handle token management securely without exposing the API key in the app bundle.
  • For web / frontend integrations, use the Iframe Integration flow, which lets the server issue session tokens instead of exposing the API key.
  • Rotate your ApiKey from the dashboard if you suspect it has been compromised.
  • User tokens can be stored client-side (they are scoped to a single user with limited permissions).