How to Use HumanCode API

version: 1.1.0

1. Workflow

This document describes how to use the HumanCode API.

1.1 Apply for Developer Account

To apply for a developer account, send an email to [e-mail] including the following information:

• Company name

• App name

• App bundle_id (iOS) or package_name (Android)

• Description of your project

After we receive your email, we will send you the APP_KEY and APP_ID. Please keep the APP_KEY private and do not transmit it through any public network. The process takes approximately 1-2 business days.

1.2 Implementation Steps

The overall workflow is illustrated in the following diagram.

Step 1: Start a Session

Developers need to create a webpage where the user clicks the "Prove I am a Human'' button. The developer webpage sends a request to the developer server to create a new session. The developer server then calls the SESSION_ID API (section 2.1) using the APP_KEY and APP_ID to obtain a session_id from the HumanCode server. The developer server sends the session_id to the developer webpage.

Step 2: Launch HumanCode App

The developer webpage initiates the Launch URL call to open HumanCode Launch Page.

• On PCs, the Launch Page displays a QR code containing: session_id and callback_url. The session_id is obtained from the previous step, and the callback_url is the URL of the developer webpage to which the user will be redirected after palm verification. Users scan the QR code using the HumanCode App to start palm verification.

• On phones, the Launch Page displays a button linked to a custom URL scheme that encodes session_id and callback_url. Users click the button to open the HumanCode App directly for palm verification.

After verification, the Launch Page polls a vcode (Verification Code) from the HumanCode Server, then forwards the vcode to the callback developer webpage.

Step 3: Verify vcode

After receiving the vcode, the developer server calls the VCODE API (section 2.3) to request verification from the HumanCode server. Upon successful verification, HumanCode returns a human_id to the developer server. The process is then complete.

2. API Definitions

We have a total of three APIs:

1. SESSION_ID API

2. LAUNCH URL

3. VCODE API

2.1 SESSION_ID API

Description:

The Developer Server requests a session_id from the HumanCode Server.

URL:

https://humancodeai.com/api/session/v2/get_id

Method:

POST

Header:

Default

Content-Type:

application/json

Query Example:

Value	Description	Field
18-byte string, e.g., a_8dcee8bb7963e46c	Your APP_ID	app_id
64-byte hmac_encoded_sign	See section 2.1 for details	sign

Body Example:

{
  "timestamp": "1706096769589",  // timestamp measured in ms
  "nonce_str": "ibuaiVcKdpRxkhJA" // random string length is 16
}

Response Example:

• Success:

{
  "code": 0,
  "msg": "ok",
  "result": {
    "session_id": "df20ea9666d3401780332e4aa26a460e"
  }
}

• Error:

{
  "code": 10002,
  "msg": "wrong APP_ID",
  "result": {}
}

Session ID Expirations:

A session ID can expire under three circumstances:

1. After 10 minutes from its creation via the SESSION_ID API.

2. Within 30 seconds of generating the verification code (vcode) following a successful authentication.

3. Instantly if the authentication fails to confirm the user's identity.

Ensure that the developer webpage completes the entire process, including launching the HumanCode webpage (section 2.2) and invoking the VCODE API (section 2.3), before the session_id expires.

2.2 Launch URL

Description:

The developer webpage launches the HumanCode Launch Page. Users scan the QR code using the HumanCode App to initiate palm verification. Upon completion, the HumanCode QR page polls from the HumanCode Server a vcode, which can be used to retrieve a human_id in a subsequent call to the VCODE API (section 2.3).

URL:

https://humancodeai.com/qr_code/

Query Example:

Field	Value	Description
session_id	32-byte string, e.g., df20ea9666d3401780332e4aa26a460e	Unique session identifier obtained from Session_ID API
callback_url	https://your_call_back_url	The URL to which the user is redirected after verification. Must specify the protocol header (http or https), cannot include any additional parameters, and must be encoded to the standard URI format using encodeURIComponent function in JavaScript.
requester	A string less than 20 bytes	The name of the product or company requesting the verification. HumanCode App will inform users on who requests the verification, and will only start palm verification upon user acceptance.

Complete Launch URL Example:

https://humancodeai.com/qr_code/?session_id=df20ea9666d3401780332e4aa26a460e&callback_url=https://your_call_back_url&requester=your_product_name

Callback URL Parameters:

Field	Value	Description
error_code	Integer error code of user authentication process	See section 4 for details.
vcode	6-digit string in successful case, for example: 413675	Verification code. This value is only meaningful when the error_code is 0.
session_id	32-byte string, e.g., df20ea9666d3401780332e4aa26a460e	Unique session identifier obtained from Session_ID API

Callback URL Example:

• Success:

https://yourcallbackurl?session_id=df20ea9666d3401780332e4aa26a460e&vcode=413675&error_code=0

• Error:

https://yourcallbackurl?session_id=df20ea9666d3401780332e4aa26a460e&vcode=error&error_code=10011

2.3 VCODE API

Description:

The developer webpage sends a request to the Developer Server to validate the session_id and vcode received from the callback URL of section 2.2. The Developer Server then calls the VCODE API of HumanCode Server and returns the validation result to the developer webpage. If the session_id and vcode are valid, the API returns a "human_id," which is a hashed version of the unique user identifier in the HumanCode system.

URL:

https://humancodeai.com/api/vcode/v2/verify

Method:

POST

Header:

Default

Content-Type:

application/json

Query Example:

Field	Value	Description
app_id	18-byte string, e.g., a_8dcee8bb7963e46c	Your APP_ID obtained from section 1.1
sign	64-byte hmac_encoded_sign	As explained in section 3

Body Example:

{
  "session_id": "df20ea9666d3401780332e4aa26a460e",  // session id
  "vcode": "879453",  // user-entered vcode
  "timestamp": "1706096769589",  // timestamp measured in ms
  "nonce_str": "ibuaiVcKdpRxkhJA"  // random string length is 16
}

Response Example:

• Success:

{
  "code": 0,
  "msg": "ok",
  "result": {
    "human_id": "u_j4l1fao2kajel3fj232odla9323faaf3"  // unique id
  }
}

• Error:

{
  "code": 10020,
  "msg": "invalid vcode",
  "result": {}
}

3. Signature

All API calls contain a signature generated by hashing a serialized JSON using HMAC-SHA256. All spaces must be removed from the data string before HMAC encoding. The Python code below demonstrates this process using separators=(',', ':') to remove spaces.

import json
import hmac
import hashlib


json_data = {"key1": "value1", "key2": "value2"}
data = json.dumps(json_data, separators=(',', ':')).encode('utf-8')
sign = hmac.new(APP_KEY.encode('utf-8'), data, hashlib.sha256).hexdigest()

4. Error Code

All API calls return a HumanCode-specific error code as an integer, which differs from standard HTTP error codes.

Code	Message
0	ok
10001	signature verification failed
10002	wrong APP_ID
10005	server error
10006	invalid parameters
10010	session_id does not exist
10011	session_id or vcode expired
10012	session is closed
10013	session is processing
10020	invalid vcode or human_id

5. Q&A

Q1: What is the usage of vcode in the VCODE API?

A: The "vcode" is for security. It is only valid for 30 seconds. Even if intercepted by a hacker, the vcode doesn't contain any user-identifiable information.

Q2: What is the unique identifier after scanning?

A: The “human_id” in the response of the VCODE API is the unique identifier associated with the HumanCode user.

Appendix - HumanCode Verification User Workflow

PC User Flow:

1. User clicks “Prove I am Human” on Partner Webpage

2. Partner Webpage launches the Launch Page which displays a QR code

3. User open HumanCode App to scan the QR code

4. Palm verification using HumanCode App

5. Launch Page automatically polls HumanCode Server

6. Launch Page returns to Partner Webpage which displays the verification result

Mobile User Flow:

1. User clicks “Prove I am Human” on Partner Webpager

2. Partner Webpage launches the Launch Page with a button

3. User clicks the button to open the HumanCode App and performs palm verification

4. Launch Page automatically polls HumanCode Server

5. Launch Page returns to Partner Webpage which displays the verification result