# How to Use HumanCode API

## 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 **<developer@humancodeai.com>** 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.

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXdLYKkWAbNH-o5coCaEkklMEldGCiG08wi7KJQORqOmO1gtlvOi7z0ygDq2s1dGRA46EB4ZyZE8f_QYHa44uaRzFLLjdbv58H6_zsUkKynpY6I1fqoJBwsXB2XKEyeuiLWWb-__bfn6oGg-PX3s-0W3Jkzw?key=y-H-k0_-sa26rb78pAi39g" alt=""><figcaption></figcaption></figure>

**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.&#x20;

* 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.&#x20;

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

**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:**

```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 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/](https://humancodeai.com/registration/index.html)

**Query Example:**

<table><thead><tr><th width="155">Field</th><th width="230">Value</th><th>Description</th></tr></thead><tbody><tr><td>session_id</td><td>32-byte string, e.g., df20ea9666d3401780332e4aa26a460e</td><td>Unique session identifier obtained from Session_ID API</td></tr><tr><td>callback_url</td><td><a href="https://your_call_back_url">https://your_call_back_url</a></td><td>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.</td></tr><tr><td>requester</td><td>A string less than 20 bytes</td><td>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.</td></tr></tbody></table>

**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:**

<table><thead><tr><th width="155">Field</th><th width="230">Value</th><th>Description</th></tr></thead><tbody><tr><td>error_code</td><td>Integer error code of user authentication process</td><td>See section 4 for details.</td></tr><tr><td>vcode</td><td><p>6-digit string in successful case, for example:</p><p>413675</p></td><td>Verification code. This value is only meaningful when the error_code is 0.</td></tr><tr><td>session_id</td><td>32-byte string, e.g., df20ea9666d3401780332e4aa26a460e</td><td>Unique session identifier obtained from Session_ID API</td></tr></tbody></table>

**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:**

```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:

```
{
  "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.<br>

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

\ <br>

## Appendix - HumanCode Verification User Workflow

### PC User Flow:

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXfEsnfASM8J1-H0xFiG-92dFNAEgF76onk7MmbuJvX6_R_mzxfnP9DNJOsqykc0LLFa5Qb_E1jjgrOkwT1MCYdpN-bshADkOxVArpE3O6N6Sqt2Cv96E-enqj4iT3lWWS3DNxfDA7quCwLSdn04ieErATTk?key=y-H-k0_-sa26rb78pAi39g" alt=""><figcaption></figcaption></figure>

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&#x20;

### Mobile User Flow:

<figure><img src="https://lh7-us.googleusercontent.com/docsz/AD_4nXdx01tw2Q7NauJJlGWggAbMIJ9voQYFaqv3H_PR1wsMOwpVuWlq7a9nXHneHfipO6cg89Rff_dcXZERW0oKTs55IirvuJW0DrEFqbAKY9cid-_Z4Z_ELilOqtmUIDCpQwrfOGVEdVFRUFN-uYKcyHF7S7a7?key=y-H-k0_-sa26rb78pAi39g" alt=""><figcaption></figcaption></figure>

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&#x20;