Authentication

HyperVerge's SDKs and APIs offer a token-based authentication method to secure your integration. The following guide details this method and its implementation.

Using Expiring Tokens (Recommended Method)

Prerequisite

Your appId and appKey are non-expiring credentials that can be accessed from the credentials tab of your HyperVerge One dashboard.

• Token-based authentication requires generating an access token using your appId and appKey. The generated token authenticates your SDK integration or API calls.
  • We recommend this approach for production environments, as it offers enhanced security compared to permanent credentials.
• Token generation must be done from the backend and should not be called from the frontend to ensure the security of your credentials.
• Access tokens have an expiry duration and require periodic regeneration to maintain secure access to our services.

IP Whitelisting

The Authentication API requires IP whitelisting for security. During initial onboarding, admin users can whitelist IP addresses through the HyperVerge One Dashboard. Once completed, whitelisted IPs maintain permanent API access.

Generating Access Token

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-state.idv.hyperverge.co/v2/auth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "appId": "<Enter_the_HyperVerge_appId>",
  "appKey": "<Enter_the_HyperVerge_appKey>",
  "expiry": "<Enter_expiry_in_seconds>",
  "transactionId": "<Enter_the_transaction_ID>",
  "workflowId": "<Enter_the_workflow_ID>",
  "authenticateOnResume": "<Enter_yes_or_no>",
  "mobileNumber": "<Enter_the_mobile_number>" or  "email": "<Enter_the_email>" // if authenticateOnResume is yes
}'

Inputs

The following table provides the details of the parameters required for the Authentication API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
appId and appKey	Mandatory	These are your credentials to access HyperVerge's system. Find them on the HyperVerge One dashboard	Not Applicable	Not Applicable
expiry	Mandatory	Specifies how long the access token will be valid, in seconds. The maximum supported value is 86400 (24 hours)	Integer	43200 (12 hours)
transactionId	Mandatory	Unique identifier of the user or application. Has to be same as the value sent during SDK initialization	Not Applicable	Not Applicable
workflowId	Mandatory	Identifier of the HyperVerge workflow. Find this on the HyperVerge One dashboard or reach out to your integration engineer	Not Applicable	Not Applicable
authenticateOnResume	Optional	Only applicable if Cross Platform Resume functionality is enabled for your workflow. Controls how user re-authentication is handled in cross-platform scenarios: set to "yes": HyperVerge handles re-authentication via OTP verification (requires either mobileNumber or email) set to"no": Your app handles re-authentication internally Ensure that your workflow is configured with the authentication flow for resuming users, i.e., when using authenticateOnResume = "yes"	"yes"/"no"	no
mobileNumber or email	Optional	Only applicable if authenticateOnResume is "yes" Used by HyperVerge to verify the user via either a mobile number or email based OTP authentication. You must provide either mobileNumber OR email, but not both The authentication flow in your workflow must be configured to support the provided contact method	Not Applicable	Not Applicable

Advanced Authentication Scenarios

Additional configuration options for cross-platform authentication and complex user flows:

1. Platform-Specific Authentication

When to use this scenario: Your application requires different authentication approaches across platforms. Some platforms use internal authentication systems, while others require HyperVerge to handle user verification.

How this scenario works: The system provides flexible authentication through the authenticateOnResume parameter. When set to "no", your application handles authentication internally without requiring contact information in token generation. When set to "yes", HyperVerge manages re-authentication using contact information you provide.

Configuration steps:

• Set authenticateOnResume to "yes" for platforms where HyperVerge handles user re-authentication (requires mobileNumber or email)
• Set authenticateOnResume to "no" for platforms where your application handles re-authentication internally
• Provide either mobileNumber or email when using authenticateOnResume = "yes" for OTP-based verification

Example use case: Users start KYC on your mobile app but receive a web link to complete additional steps. Your mobile app handles authentication internally (authenticateOnResume = "no"), while the web link uses HyperVerge's authentication (authenticateOnResume = "yes" with user's contact info).

2. Universal HyperVerge Authentication

When to use this scenario: Your application requires HyperVerge to handle all user re-authentication across every platform and you have access to user contact information during token generation.

How this scenario works: The system enables consistent authentication across all platforms using OTP verification, which users complete through mobile number or email whenever they resume their workflow on any platform.

Configuration steps:

• Set authenticateOnResume to "yes"
• Provide either mobileNumber or email during token generation
• Ensure your workflow includes the 'CPR Auth' object configuration

Example use case: Enterprise applications requiring consistent security policies across web, mobile, and desktop platforms where HyperVerge manages all authentication touchpoints.

3. Universal HyperVerge Authentication (With contact information retrieval)

When to use this scenario: Your application requires HyperVerge to handle re-authentication across platforms but you don't have user contact information (mobileNumber or email) during token generation.

How this scenario works: HyperVerge collects contact information during the workflow execution through integrated mobile/email verification steps. The credentials are obtained during the process and cross-platform resume functionality is enabled for you without requiring user contact information at token generation.

Configuration steps:

• Include mobile/email verification steps in your primary workflow
• Contact your integration engineering team to configure the 'CPR Auth' object in your workflow
• Enable contact collection within the workflow rather than during token generation

Example use case: Public-facing applications where users begin verification without providing contact information upfront, but HyperVerge collects this data during the workflow to enable cross-platform resume capabilities.

4. Client-Managed Authentication (No Cross-Platform Resume)

When to use this scenario: Your application handles all user authentication internally across all platforms and you don't require cross-platform resume functionality. Users complete their verification within a single platform session.

How this scenario works: The system bypasses HyperVerge's authentication mechanisms entirely. Your application manages user sessions, login states, and re-authentication using your own systems. No cross-platform resume capabilities are enabled, and users must complete their workflow within the platform where they started.

Configuration steps:

• Set authenticateOnResume to "no" across all platforms
• Your workflow does not require the 'CPR Auth' object configuration
• Handle all authentication logic within your application architecture

Example use case: Native mobile applications with robust internal authentication systems where users complete the entire verification process within the app session, without needing to switch between platforms or resume workflows externally.

Success Response

The following code snippet demonstrates a response from the Authentication API, if the access token gets generated successfully:

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "authToken": "<The_generated_Access_Token>"
    }
}

Success Response Details

The following table outlines the details of the success response from the Authentication API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code of the response
result	object	Contains the authentication token and associated metadata
result.authToken	string	The generated access token used for authentication

Error Responses

The following are some error responses from the Authentication API:

Invalid Request Body

{
  "statusCode": 400,
  "status": "failure",
  "error": "Request Body Validation has failed",
  "errorCode": "invalid_request_body"
}

Unauthorized Access

{
  "statusCode": 401,
  "status": "failure",
  "error": "IP is not whitelisted or authorization failed",
  "errorCode": "unauthorized_access"
}

Missing/Invalid Workflow ID

{
  "statusCode": 404,
  "status": "failure",
  "errorCode": "workflow_not_found"
}

Unique ID Mismatch

{
  "statusCode": 409,
  "status": "failure",
  "errorCode": "unique_id_conflict"
}

Internal Server Error

{
  "statusCode": 500,
  "status": "failure",
  "error": "Internal server error",
  "errorCode": "internal_server_error"
}

Error Response Details

A failure or error response from the API contains a failure status with a relevant status code and error message. The following table lists all error responses:

Status Code	Error Code	Error	Error Description
400	invalid_request_body	Request Body Validation has failed	The values in the request body are either missing or invalid
Types of invalid_request_body errors
400	invalid_request_body	"appId" is required	The appId field is missing from the request
400	invalid_request_body	"appKey" is required	The appKey field is missing from the request
400	invalid_request_body	"transactionId" is required	The transactionId field is missing
400	invalid_request_body	"workflowId" is required	The workflowId field is missing
400	invalid_request_body	authenticateOnResume is required	The authenticateOnResume field is missing
400	invalid_request_body	authenticateOnResume must be one of [yes, no]	The authenticateOnResume value is not "yes" or "no"
400	invalid_request_body	"mobileNumber" must be a string	The mobileNumber is provided but not a string type
400	invalid_request_body	"email" must be a string	The email is provided but not a string type
400	invalid_request_body	Only one of mobileNumber or email should be sent	Both mobileNumber and email were included in the request
400	invalid_request_body	"expiry" must be greater than or equal to 1	The expiry value is less than 1 second
400	invalid_request_body	"expiry" must be less than or equal to 86400	The expiry value exceeds the maximum allowed (86400 seconds = 24 hours)
400	invalid_request_body	"expiry" must be a number	The expiry value is not a numeric type
401	unauthorized_access	Missing/Invalid Credentials	IP is not whitelisted or authorization failed
404	workflow_not_found	Not Applicable	The entered Workflow ID is missing/incorrect
409	unique_id_conflict	Conflict in unique ID stored in DB vs what is generated with API inputs	The transactionId provided conflicts with an existing transaction in the database
500	internal_server_error	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution

Using Expiring Tokens (Deprecated Method)

This is the legacy token-based authentication method that provides a simpler approach. It generates access tokens using only your appId and appKey credentials, without requiring additional parameters like transactionId or workflowId. This method is still functional but lacks the advanced features and security enhancements available in the recommended method.

The access tokens have an expiry duration and require you to regenerate them periodically.

Generating Access Token

To generate an access token, make the following API call:

curl -X POST 'https://auth.hyperverge.co/login' \
--header 'Content-Type: application/json' \
--data-raw '{
  "appId": "<Enter_the_HyperVerge_appId>",
  "appKey": "<Enter_the_HyperVerge_appKey>",
  "expiry": 300
}'

note

• The parameters appId and appKey can be accessed from the 'credentials' tab of the dashboard
• The value for the expiry parameter should be an integer representing seconds.
  • The default value of the parameter when not passed explicitly is 43200 (equivalent to 12 hours).
  • The maximum value supported is 86400 (equivalent to 24 hours).

Success Response

If the access token got generated successfully, the following response is returned:

{ 
  "result":{ 
    "token":"<Access Token>"           
  } 
}

Error Response

A failure or error response from the API contains a failure status with a relevant status code and error message. The following are the error responses:

Missing Credentials

{
    "statusCode": "400",
    "status": "failure",
    "error": "Missing/Invalid credentials"
}

Invalid Expiry (too small)

{
  "statusCode": 400,
  "status": "failure",
  "error": "Expiry should be greater than 0"
}

Invalid Expiry (too large)

{
  "statusCode": 400,
  "status": "failure",
  "error": "Expiry should be within 24 hours from current time"
}

Invalid Credentials

{
  "statusCode": "401",
  "status": "failure",
  "error": "Missing/Invalid credentials"
}

Internal Server Error

{
  "statusCode": 500,
  "status": "failure",
  "error": "Internal Server Error"
}

Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message. The following table lists all error responses:

Status Code	Error Message	Error Description
400	Missing/Invalid credentials	The request is missing the mandatory appId , or appKey, or both
400	Expiry should be greater than 0	The expiry value provided is less than or equal to 0 seconds
400	Expiry should be within 24 hours from current time	The expiry value exceeds the maximum allowed duration of 24 hours (86400 seconds)
401	Missing/Invalid credentials	The request has invalid values for appId or appKey or combination of both
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution