# Web SDK Integration Guide ## Overview 1. [Requirements](/web-sdk-integration-guide.md#requirements) 2. [Steps](/web-sdk-integration-guide.md#steps) 3. [API Documentation](/web-sdk-integration-guide.md#api-documentation) 4. [Error Codes](/web-sdk-integration-guide.md#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 and ask for Web Login Integration Set-up **The authentication process can be illustrated in the following diagram:** ![](/files/-MbrkNQawFc60PKATprT) ## Steps 1. [Create a Log-in Page](/web-sdk-integration-guide.md#1-create-a-log-in-page) 2. [Create a Log-in API](/web-sdk-integration-guide.md#2-create-a-log-in-api) 3. [Create Log-in Callback API](/web-sdk-integration-guide.md#3-create-a-log-in-callback-api) ### 1. Create a Log-in Page Create a Log-in page that contains this button. ![](/files/-Mbrl9VwKPj9LDUXNdp_) Get the Log in button image and put this script below into your Web App: {% file src="/files/-MhPdfLhiygBUCTtkMgS" %} Log-in Button Image {% endfile %} ``` Anonymous Login with humanID ``` ### 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](/web-sdk-integration-guide.md#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: ``` ?et= ``` 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](/web-sdk-integration-guide.md#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.
**Handle Error Response** If log-in failed, humanID will redirect to configured **Log-in Callback URL** that is formatted: ``` ?code=&message= ``` To check whether log-in failed or not, simply check if parameter `et` appended in callback URL
## 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` | `` | | `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` | `` | | `client-secret` | `` | | `Content-Type` | `application/json` | * Body: ``` { "exchangeToken": "0BYLCicta3dO5DrTkrfQxo7Z4hxmyAh5OwuVPEGS5SlnBGwY+A/t7BNKzGcZFGqGOnI97nGQJ6SGoMf8vyux+D3AYmk63CR9AUnO7f+zlTL4MX9t2OhBdMZoLNP21ucvnTjiR5EIO7qwnFRVN4VquMCUMV8Kmt7N1s6V3yXHmDM=" } ``` * Response Example * Success: ``` { "success": true, "code": "OK", "message": "Success", "data": { "userAppId": "", "countryCide": "ID" } } ``` ## Error Codes See a full list of [error codes](https://github.com/human-internet/humanid-weblogin#error-codes) on our Github. --- # 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://docs.human-id.org/web-sdk-integration-guide.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.