Web SDK Link

A Web SDK Link is a hosted, one-time verification link you can send an end user instead of integrating the IDV API yourself. The user opens the link in their browser, completes verification on a hosted page, and the result is recorded against the flowId and groupId the link was generated for. Your merchant secret is never exposed to the browser.

This requires a flow that belongs to a group — see Flows & Groups if you haven't created these yet.

Option A: Generate a Link From the Portal

1. Open the Configuration page and select the flow you want to use.
2. Click Generate Web SDK Link.
3. Enter a User ID — your own identifier for the end user (this becomes externalUserId/userId for the session).
4. Select a Group containing this flow. If none exist, create one first on the Groups page.
5. Click generate. You'll get a shareable link and a QR code — send the link to the user, or have them scan the QR code on a mobile device.

Option B: Generate a Link via the API

POST /v2/sdk/session/web-sdk-link

Accepts the same authentication as /v2/idv/verify (Basic Auth with your merchant credentials, or a portal session).

Request Body

{
  "userId": "user-12345",
  "groupId": "group_e5f6g7h8",
  "flowId": "flow_a1b2c3d4"
}

All three fields are required strings. The API validates that flowId and groupId belong to your merchant account, and that the flow is a member of that group.

Example

curl -X POST 'https://api2.cycurid.com/v2/sdk/session/web-sdk-link' \
  -u '{{merchantApiKey}}:{{merchantSecret}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "user-12345",
    "groupId": "group_e5f6g7h8",
    "flowId": "flow_a1b2c3d4"
  }'

Response

{
  "url": "https://websdk.cycurid.com?iswebsdklink=true&token=<one-time-token>"
}

The link token is valid for 10 minutes and can only be exchanged once.

Error Responses

Status	Meaning
400	userId, groupId, or flowId missing or not a string
404	Flow not found for your merchant account
404	Group not found for your merchant account
400	Flow is not a member of the specified group

What Happens When the User Opens the Link

1. The hosted page reads the token query parameter and calls POST /v2/sdk/session/exchange with { "token": "..." } — no authentication required for this call.
2. The backend validates the token (unused, not expired), applies geo-blocking (checking both your account-wide blocked countries and the flow's own geo-blocked list), and creates a session.
   • If the detected country is blocked, this call returns 403 with { "error": "geo_blocked", "detectedCountry": "...", "message": "..." }.
3. On success, the exchange returns a short-lived (10 minute) access token along with the flow's resolved configuration:

{
  "access_token": "...",
  "session_id": "...",
  "sdk_id": "...",
  "is_sandbox": false,
  "expires_in": 600,
  "userId": "user-12345",
  "groupId": "group_e5f6g7h8",
  "flowId": "flow_a1b2c3d4",
  "defaultFields": { "...": true },
  "defaultDocumentTypes": ["PASSPORT"],
  "countryOverrides": [],
  "biometricType": "selfie",
  "documentUploadType": "fileUpload"
}

4. The hosted page renders the verification form based on defaultFields/defaultDocumentTypes/biometricType, then calls POST /v2/idv/verify directly from the browser using access_token as a Bearer token (see Authentication).

Biometric & Document Capture Modes

biometricType and documentUploadType tell the hosted page how to capture the applicant's selfie and documents, based on the flow's configuration:

biometricType	Hosted Page Behavior
selfie	Prompts the user to upload a static selfie image
live selfie	Captures a selfie live via the device camera
liveness	Runs a liveness check (e.g. a guided head movement) via the device camera

documentUploadType	Hosted Page Behavior
fileUpload	User selects an existing image/PDF file for each document
fileCapture	User captures each document live via the device camera

note

These values only affect how the hosted page captures input. The resulting request to /v2/idv/verify is unchanged either way — the captured biometric is always submitted as the selfie field, and documents are always submitted under their standard field names (passportFront, driversFront, etc.). See File Upload Fields.

Next Steps

• IDV API Reference — call /v2/idv/verify directly instead
• Flows & Groups — configure the flow and group this link uses