Authentication

Every Vlens API request requires two credentials:

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/IdentityUserSession/CreateAuthSession

Refreshing tokens

Use the refresh token to obtain a new access token without re-authenticating:

$
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"}'

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 / 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).