> 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 AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vlenseg.com/_mcp/server.

# Authentication

Every Vlens API request requires two credentials:

| Header          | Value                              | Required on                                      |
| --------------- | ---------------------------------- | ------------------------------------------------ |
| `ApiKey`        | Static key assigned to your tenant | Every request                                    |
| `Authorization` | `Bearer <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.

```bash
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:

```json
{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expireInSeconds": 86400,
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshTokenExpireInSeconds": 604800
  }
}
```

**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.

```bash
# 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](https://console.cloud.google.com/) and [Azure AD B2C](https://docs.microsoft.com/azure/active-directory-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:

```bash
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"}'
```

Refresh tokens are long-lived (7 days by default). Rotate them server-side and never expose them to client-side code.

## Request headers

A complete request with both credentials looks like this:

```bash
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](/iframe-session) 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).