# Web SDK Integration Guide

## Overview

1. [Requirements](#requirements)
2. [Steps](#steps)
3. [API Documentation](#api-documentation)
4. [Error Codes](#error-codes)

## Requirements

* **humanID Server Credentials,** Server Credentials consist of:
  * Server Client ID
  * Server Client Secret
* **App Back-end,** to receive authentication Callback from humanID

> Note: Feature to obtain Server Credentials and to configure Callback URL is not yet available at humanID Developer Console. Please contact <developers@human-id.org> and ask for Web Login Integration Set-up

**The authentication process can be illustrated in the following diagram:**

![](https://2726894056-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MbbSWPPdzqwBMlWppLN%2F-MbriDOOpfTbjFcS1fk9%2F-MbrkNQawFc60PKATprT%2FhumanID%20WebSDK.svg?alt=media\&token=751243ff-2eef-40c1-b268-cfd2753634c9)

## Steps

1. [Create a Log-in Page](#1-create-a-log-in-page)
2. [Create a Log-in API](#2-create-a-log-in-api)
3. [Create Log-in Callback API](#3-create-a-log-in-callback-api)

### 1. Create a Log-in Page

Create a Log-in page that contains this button.

![](https://2726894056-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MbbSWPPdzqwBMlWppLN%2F-MbriDOOpfTbjFcS1fk9%2F-Mbrl9VwKPj9LDUXNdp_%2FhID%20Login.png?alt=media\&token=e46e46e3-fa73-447d-82b3-3afd7f9f8914)

Get the Log in button image and put this script below into your Web App:

{% file src="<https://2726894056-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MbbSWPPdzqwBMlWppLN%2F-MhPbxNZtbjogRBwczuG%2F-MhPdfLhiygBUCTtkMgS%2Fanonymous-login.svg?alt=media&token=946a6e27-cf8c-41ac-8bf8-dc5479cf335e>" %}
Log-in Button Image
{% endfile %}

```
<a href="REPLACE_WITH_TARGET_URL">
    <img src="anonymous-login.svg" alt="Anonymous Login with humanID" height="27"/>
<a>
```

### 2. Create a Log-in API

When user clicks the log-in with button, the Web App will make a request to the App Backend and then the page will be redirected to web-login.human-id.org.

To obtain Log-in URL, App Back-end will call **API Request Web Log-in Session** ([See Documentation below](#api-request-web-log-in-session)). The API call must be done between Host-to-Host in order to protect Server Credentials.

Once App Backend received a response that contains Log-in URL, redirect the page to the given URL to open **humanID Web Log-in Page**

### 3. Create a Log-in Callback API

After the user successfully Log-in with humanID, the page will be redirected to a registered **Log-in Callback URL** (registered on Developer Console). Callback URL contains **Exchange Token**, which is a URL Encoded token that will be used to obtain User ID.

A Log-in callback URL is formatted:

```
<SUCCESS_REDIRECT_URL>?et=<URL_ENCODED_EXCHANGE_TOKEN>
```

For Example:

```
https://api.filmreview.example.com/humanid-callback?et=9F27%2BOpExCGqTrk6caay66fb%2FumdjAN0LnmTRgxj%2Fq70FplDictSay0lUQvTqkJ6S7agUwbfGN5bhbbJnRbrIpBI1goDa7qBgN88ZjYnDZDI9YrgEV1qlxTNyrGQp79Oc4rCQOemZT162StlEXsiEeAZRAwDJfele%2F6vQszqc2PtlwQ%3D%3D
```

URL Decode **Exchange Token** and use it as a parameter to call **API Exchange Token** ([See Details](#api-exchange-token)) to obtain User ID.

Once App Backend receives response from API call, use given User ID to authorize User so User could access the Web App contents.<br>

**Handle Error Response**

If log-in failed, humanID will redirect to configured **Log-in Callback URL** that is formatted:

```
<FAILED_REDIRECT_URL>?code=<ERROR_CODE>&message=<ERROR_MESSAGE>
```

To check whether log-in failed or not, simply check if parameter `et` appended in callback URL<br>

## API Documentation

#### API Request Web Log-in Session

Endpoint URL

```
POST https://core.human-id.org/v0.0.3/server/users/web-login
```

Request

* Headers:

| **Key**         | **Value**                |
| --------------- | ------------------------ |
| `client-id`     | `<SERVER_CLIENT_ID>`     |
| `client-secret` | `<SERVER_CLIENT_SECRET>` |
| `Content-Type`  | `application/json`       |

* Query Parameters:

| **Key**            | **Value** | **Description**  |
| ------------------ | --------- | ---------------- |
| `lang`             |           | Language to Show |
| `priority_country` |           |                  |

* Response Example
  * Success:

```
{
"success": true ,
"code": "OK",
"message": "Success",
"data": {
    "webLoginUrl": "https://web-login.human-id.org/login?t=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwdXJwb3NlIjoid2ViLWxvZ2luL3JlcXVlc3QtbG9naW4tb3RwIiwic2lnbmF0dXJlIjoiODNiMDMxNjMwMTkzMjE5ZjMzNWM2MGI0OGU2MGQ5MzVlZWQ5ZDkzNDNlYjRiZmFjYzRlOTFmMTUxOTVhMDVlNyIsImlhdCI6MTU5OTI3MTczNSwiZXhwIjoxNTk5MjcyMDM1LCJzdWIiOiJTRVJWRVJfR1hJVFM3TlZZM0RETVozNVdVSDdDWCIsImp0aSI6InR1SWdOdU1LMjBseGI3a2pGeG9DUFNMeUx2UE8yNkJuWmtmMHc1WjZvTG9PcTlhZkRMblJGSHh0VHVGZllRSGoifQ.CVUA8DYOAk0nbu0_ftTFNMwtfCJ32hCqY_6MKP43Sg8&a=IO5T8PZH2O15N8SV&lang=en"
    }
}
```

* Error: Invalid Server Credentials

```
{ "success": false, "code": "401", "message": "Unauthorized" }
```

### API Exchange Token

* Endpoint URL

```
POST https://core.human-id.org/v0.0.3/server/users/exchange
```

* Request
  * Headers:

| **Key**         | **Value**                |
| --------------- | ------------------------ |
| `client-id`     | `<SERVER_CLIENT_ID>`     |
| `client-secret` | `<SERVER_CLIENT_SECRET>` |
| `Content-Type`  | `application/json`       |

* Body:

```
{
"exchangeToken": "0BYLCicta3dO5DrTkrfQxo7Z4hxmyAh5OwuVPEGS5SlnBGwY+A/t7BNKzGcZFGqGOnI97nGQJ6SGoMf8vyux+D3AYmk63CR9AUnO7f+zlTL4MX9t2OhBdMZoLNP21ucvnTjiR5EIO7qwnFRVN4VquMCUMV8Kmt7N1s6V3yXHmDM="
}
```

* Response Example
  * Success:

```
{
    "success": true,
    "code": "OK",
    "message": "Success",
    "data": {
        "userAppId": "<UNIQUE_USER_ID>",
        "countryCide": "ID"
    }
}
```

## Error Codes

See a full list of [error codes](https://github.com/human-internet/humanid-weblogin#error-codes) on our Github.