CPR API Reference

[POST] /v2/auth/token

Overview

The /v2/auth/token API generates authentication tokens for cross-platform resume (CPR) workflows. It creates a uniqueId based on user credentials (mobileNumber or email) and returns a JWT token for subsequent authentication.

Endpoint

Method	POST
URL	https://ind-state.idv.hyperverge.co/v2/auth/token
Authentication	Required

Authentication

warning

This API requires:

• appId and appKey passed in the body must be valid credentials
• IP whitelisting required — a valid IP must be whitelisted for the appId

The API also supports signature validation.

Request Parameters

Parameter	Type	Required	Default	Description
appId	String	Yes	-	appId shared by HV
appKey	String	Yes	-	appKey shared by HV
transactionId	String	Yes	-	Unique identifier for a transaction/user
workflowId	String	Yes	-	Identifier for the workflow
authenticateOnResume	String	No	no	Must be 'yes' or 'no'. Controls authentication on workflow resumption
expiry	Number	No	43200 (12 hours)	Token expiry in seconds. Between 1 and 86400 (24 hours)
mobileNumber	String	No	-	User's mobile number — mutually exclusive with email
email	String	No	-	User's email — mutually exclusive with mobileNumber

caution

You must provide either mobileNumber OR email, but not both.

More info about mobileNumber/email

• Required if authenticateOnResume is yes, so HyperVerge can verify the user
• Link to understand different scenarios in CPR Auth (Miro)
• The SDK supports both mobile-based OTP and email-based OTP for verification

Success Response (200 OK)

{
  "statusCode": 200,
  "status": "success",
  "result": {
    "authToken": "Bearer <token>",
    "metadata": {
      "appId": "<appId>",
      "transactionId": "<transactionId>",
      "workflowId": "<workflowId>",
      "journeyId": "<journeyId>"
    }
  }
}

Error Responses

Generic error response structure:

{
  "statusCode": "<statusCode>",
  "status": "failure",
  "error": "<error>",
  "errorCode": "<errorCode>"
}

Status Code	Error Code	Description
400	invalid_request_body	Request body validation failed
401	unauthorized_access	IP not whitelisted or authorization failed
404	workflow_not_found	Workflow not found (incorrect workflowId)
409	unique_id_conflict	Conflict in unique ID stored in DB vs generated
500	internal_server_error	Server error

Detailed error messages for invalid_request_body

Error Message	Condition
"appId" is required	appId field missing
"appKey" is required	appKey field missing
"transactionId" is required	transactionId field missing
"workflowId" is required	workflowId field missing
"authenticateOnResume" must be one of [yes, no]	Invalid value
"mobileNumber" must be a string	Wrong type
"email" must be a string	Wrong type
Only one of mobileNumber or email should be sent	Both provided
"expiry" must be greater than or equal to 1	Below minimum
"expiry" must be less than or equal to 86400	Above maximum
"expiry" must be a number	Wrong type

Token Generation Logic

authObject (mobileNumber/email)	authenticateOnResume	Create uniqueId?	Embed uniqueId in Token?
Provided	"yes"	Yes	No
Provided	"no"	Yes	Yes
Not Provided	"yes"	No	No
Not Provided	"no"	No	No

Key takeaways:

• authenticateOnResume = "yes" + authObject provided: uniqueId created but NOT in token → client must re-authenticate on resume
• authenticateOnResume = "no" + authObject provided: uniqueId created AND in token → client resumes without extra auth
• No authObject → no uniqueId regardless of authenticateOnResume

Flowchart

flowchart TD
    A[Start] --> B[Validate Request Parameters]
    B --> C[Check IP Whitelisting]
    C --> D{Transaction State Exists?}
    D -->|Yes| E{Has Expired?}
    D -->|No| F[Create Empty State]
    E -->|Yes| G[Continue with Expired State]
    E -->|No| H{Create uniqueId?}
    G --> H
    F --> I[Generate uniqueId from auth credentials]
    H -->|Yes| I
    H -->|No| J[Skip uniqueId Creation]
    I --> K{Should Embed uniqueId in Token?}
    J --> K
    K -->|Yes| L[Generate Token with uniqueId]
    K -->|No| M[Generate Token without uniqueId]
    L --> N[Return Token and Metadata]
    M --> N

Sample cURL

curl --location 'https://ind-state.idv.hyperverge.co/v2/auth/token' \
--header 'Content-Type: application/json' \
--data '{
    "appId": "<appId>",
    "appKey": "<appKey>",
    "transactionId": "<transactionId>",
    "workflowId": "<workflowId>",
    "authenticateOnResume": "yes",
    "mobileNumber": "<mobileNumber>"
}'

---

[POST] /v2/generate-auth-token [OLD]

warning

This endpoint is being replaced by /v2/auth/token above. Use the new endpoint for all new integrations.

Legacy endpoint details

Endpoint: POST https://ind-state.idv.hyperverge.co/v2/generate-auth-token

Same parameters as the new endpoint. Key differences:

• Uses userAuthRequired instead of authenticateOnResume
• Uses authObject instead of top-level mobileNumber/email
• Response uses token instead of authToken

---

[POST] /v2/generate-unique-id (Deprecated)

danger

This endpoint is deprecated. Use /v2/auth/token instead.

Deprecated endpoint details

Endpoint: POST https://ind-state.idv.hyperverge.co/v2/generate-unique-id

This API generates a uniqueId for an appId, transactionId & workflowId, and creates a new state if state is not present in the backend.

Authentication is via appId/appKey headers or authorization header, plus IP whitelisting.