How to Use HumanCode API（H5）

version 1.0.7

1. Workflow

This document explains how to use the HumanCode API for Proof-of-Humanity.

1.1 Apply for Developer Account

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

Company name
App name
App bundle_id (iOS) 、package_name (Android) or domain (Website)
Description of your project

After we receive your email, we will send you the APP_ID and APP_KEY. 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: Integrate HumanCode Webpage

Depending on whether the user is registered with HumanCode, the developer webpage will call either the REGISTRATION URL (section 2.2) or the VERIFICATION URL (section 2.3):

For new users, the developer webpage initiates the REGISTRATION URL call to open the HumanCode webpage, passing two parameters: 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 completing the verification process.
For existing HumanCode users, the developer webpage initiates the VERIFICATION URL call to open the HumanCode webpage, passing three parameters: session_id, callback_url, and human_id. The human_id is a unique user identifier in HumanCode.

The user follows the instructions on the HumanCode webpage to scan their palm. Once the scan is completed, the HumanCode server sends a vcode (Verification Code) to the HumanCode webpage, which then transmits the vcode to the callback developer webpage.

Step 3: Verify vcode

After receiving the vcode, the developer server calls the VCODE API (section 2.4) 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 four APIs:

SESSION_ID API
REGISTRATION URL
VERIFICATION URL
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:

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:

{
  "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:

After 10 minutes from its creation via the SESSION_ID API.
Within 30 seconds of generating the verification code (vcode) following a successful authentication.
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 2.3) and invoking the VCODE API (section 2.4), before the session_id expires.

2.2 REGISTRATION URL

Description: The developer webpage launches the HumanCode webpage in registration mode to register the user for the first time. Upon successful registration, the developer webpage receives a vcode, which can be used to retrieve a human_id in a follow-up call to the VCODE API (section 2.4). Store this human_id for future user verification requests.

URL: https://humancodeai.com/registration/index.html

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. e.g., encodeURIComponent(https://your_call_back_url)

1716259499345

timestamp (in milliseconds) is placed at the end

Complete Launch URL Example:

https://humancodeai.com/registration/index.html?session_id=df20ea9666d3401780332e4aa26a460e&callback_url=https://your_call_back_url&ts=1716259499345

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 11, 12.

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=12

Error:

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

2.3 VERIFICATION URL

Description: For an existing HumanCode user, the developer webpage launches the HumanCode webpage in verification mode.

URL: https://humancodeai.com/verification/index.html

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

human_id

34-byte string, e.g., u_a31cad3531f08787a0f00d973882418f

Unique user identifier obtained in section 2.4.

1716259499345

timestamp (in milliseconds) is placed at the end

Complete Launch URL Example:

https://humancodeai.com/verification/index.html?session_id=df20ea9666d3401780332e4aa26a460e&callback_url=https://your_call_back_url&human_id=u_a31cad3531f08787a0f00d973882418&ts=1716259499345

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

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=20

Error:

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

2.4 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 and 2.3. 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

palm already registered (a valid vcode is returned)

new palm registered (a valid vcode is returned)

registration failed (not a real human)

verification succeeded (a valid vcode is returned)

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

10020

invalid vcode or human_id

10021

verification failed (not the registered user)

10030

webview is not supported

10040

spoof detected

5. Q&A

Q1: What is the usage of vcode in the VCODE API? A: The "vcode" is designed 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.

Last updated 11 months ago