# How to Use HumanCode API（H5） ## 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 **** 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.

Workflow 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: 1. SESSION\_ID API 2. REGISTRATION URL 3. VERIFICATION URL 4. VCODE API ### 2.1 SESSION\_ID API **Description:**\ The Developer Server requests a session\_id from the HumanCode Server. **URL:**\ **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:** ```json { "timestamp": "1706096769589", // timestamp measured in ms "nonce_str": "ibuaiVcKdpRxkhJA" // random string length is 16 } ``` **Response Example:** * **Success:** ```json { "code": 0, "msg": "ok", "result": { "session_id": "df20ea9666d3401780332e4aa26a460e" } } ``` * **Error:** ```json { "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 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:**\ **Query Example:** | Field | Value | Description | | ------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | session\_id | 32-byte string, e.g., df20ea9666d3401780332e4aa26a460e | Unique session identifier obtained from Session\_ID API | | callback\_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)

| | ts | 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:**
FieldValueDescription
error_codeInteger error code of user authentication processSee 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_id32-byte string, e.g., df20ea9666d3401780332e4aa26a460eUnique 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:**\ **Query Example:** | Field | Value | Description | | ------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | session\_id | 32-byte string, e.g., df20ea9666d3401780332e4aa26a460e | Unique session identifier obtained from Session\_ID API | | callback\_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)

| | human\_id | 34-byte string, e.g., u\_a31cad3531f08787a0f00d973882418f | Unique user identifier obtained in section 2.4. | | ts | 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:**
FieldValueDescription
error_codeInteger error code of user authentication processSee 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_id32-byte string, e.g., df20ea9666d3401780332e4aa26a460eUnique 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:**\ **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:** ```json { "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:** ```json { "code": 0, "msg": "ok", "result": { "human_id": "u_j4l1fao2kajel3fj232odla9323faaf3" // unique id } } ``` * **Error:** ```json { "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. ```python 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 | | 11 | palm already registered (a valid vcode is returned) | | 12 | new palm registered (a valid vcode is returned) | | 13 | registration failed (not a real human) | | 20 | 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://h5apidoc.humancodeai.com/how-to-use-humancode-api-h5.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.