> For the complete documentation index, see [llms.txt](https://legacy-docs.usesmileid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://legacy-docs.usesmileid.com/integration-options/web-mobile-web/web-integration.md).

# Web Integration

The web Integration Widget is a client-side component that your web site or web application can use to have your users verify their identity with Smile ID. The web integration widget is a hosted solution and handles the image capture, user consent, job submission and error handling for the product you are want to run.

## Guide

* Set up a callback endpoint
* Choose a Server to Server Library
* Create an endpoint for the web token
* Install the Web Integration
* Use the Web Integration

### Set Up a Callback Endpoint

All jobs using the Web Integration are asynchronous. As such, having a Callback Endpoint in your Server is important.

Here's our guide on how to [set up a callback endpoint](https://docs.usesmileid.com/further-reading/faqs/how-do-i-setup-a-callback).

### Choose a Server to Server Library

We currently have [Server to Server Libraries](/integration-options/server-to-server.md) in the following languages / run-times.

* [Ruby](/integration-options/server-to-server/ruby.md)
* [Python](/integration-options/server-to-server/python.md)
* [Java](/integration-options/server-to-server/java.md)
* [NodeJS](/integration-options/server-to-server/javascript.md)
* [PHP](/integration-options/server-to-server/php.md)

In this documentation, our code samples will use the NodeJS Server to Server library.

### Create an EndPoint for the Web Token

Using your chosen Server to Server library, create an endpoint for fetching a token.

#### Option 1: Using the Server-to-Server Library

This is our sample NodeJS script that uses our NodeJS Server-to-Server library.

```javascript
const express = require('express');
const { v4: UUID } = require('uuid');
const cors = require('cors');

if (process.env.NODE_ENV === 'development') {
  const dotenv = require('dotenv');

  dotenv.config();
}

const SIDCore = require('smile-identity-core');
const SIDWebAPI = SIDCore.WebApi;

const app = express();

app.use(cors());
app.use(express.json({ limit: '500kb' }));

// NOTE: you can make this endpoint use the `POST` method,
// and pass a User ID, Job ID, or Product Type from your system.
app.get('/token', async (req, res, next) => {
  try {
    const { PARTNER_ID, CALLBACK_URL, API_KEY, SID_SERVER } = process.env;
    const connection = new SIDWebAPI(
      PARTNER_ID,
      CALLBACK_URL,
      API_KEY,
      SID_SERVER
    );

    const request_params = {
      user_id: `user-${UUID()}`,
      job_id: `job-${UUID()}`,
      product: 'biometric_kyc', // Choose one of 'authentication', 'basic_kyc', 'smartselfie', 'biometric_kyc', 'enhanced_kyc', 'doc_verification'
      callback_url: CALLBACK_URL
    };

    const result = await connection.get_web_token(
      request_params
    );

    res.json(result);
  } catch (e) {
    // handle error
    console.error(e);
  }
```

This is all the Server-Side configuration needed for the Web Integration.

***

#### Option 2: Using the REST API

If you prefer to call the API directly without a server-to-server library, you can request a token from the following endpoint.

**Endpoint:** `POST` <https://api.smileidentity.com/v1/token>

**Request Body:**

```json
{
  "source_sdk": "rest_api",
  "source_sdk_version": "1.0.0",
  "signature": "{{signature}}",
  "timestamp": "{{time_stamp}}",
  "user_id": "1236",
  "job_id": "1236",
  "country": "NG",
  "id_type": "Passport",
  "product": "Doc_verification",
  "callback_url": "",
  "partner_id": "{{partner_id}}"
}
```

<table><thead><tr><th width="181.50390625">Field</th><th width="99.16015625">Type</th><th width="106.4375">Required</th><th width="369.1640625">Description</th></tr></thead><tbody><tr><td><code>source_sdk</code></td><td>string</td><td>Yes</td><td>The integration option you are using. For the REST API, send the value as "rest_api"</td></tr><tr><td><code>source_sdk_version</code></td><td>string</td><td>Yes</td><td>The version of the integration option you are using</td></tr><tr><td><code>signature</code></td><td>string</td><td>Yes</td><td>The outgoing signature to authenticate the request from you to Smile ID.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Yes</td><td>The timestamp used to calculate the signature in ISO date/time format</td></tr><tr><td><code>user_id</code></td><td>string</td><td>Yes</td><td>A value generated by you to track users on your end. This value must be unique, can be any string, and can follow your identifier convention.</td></tr><tr><td><code>job_id</code></td><td>string</td><td>Yes</td><td>A value generated by you to track jobs on your end. This value must be unique, can be any string, and can follow your identifier convention.</td></tr><tr><td><code>country</code></td><td>string</td><td>Yes</td><td>Country code. Link to country codes <a href="https://docs.usesmileid.com/supported-id-types/for-individuals-kyc/backed-by-id-authority#know-your-customer-kyc">here</a>.</td></tr><tr><td><code>id_type</code></td><td>string</td><td>Yes</td><td>Supported ID type. <a href="https://docs.usesmileid.com/supported-id-types/for-individuals-kyc/backed-by-id-authority">More information</a>.</td></tr><tr><td><code>product</code></td><td>string</td><td>Yes</td><td><p>one of the Smile ID products. <code>"biometric_kyc"</code> <code>"doc_verification</code> <code>"authentication"</code> <code>"basic_kyc"</code> <code>"smartselfie"</code> <code>"enhanced_kyc"</code> <code>"enhanced_document_verification"</code></p><p><code>"e_signature"</code></p></td></tr><tr><td><code>callback_url</code></td><td>string</td><td></td><td>URL to receive the job result webhook</td></tr><tr><td><code>partner_id</code></td><td>string</td><td>Yes</td><td>A unique number assigned by Smile ID to your account. Can be found with your API key <a href="https://portal.usesmileid.com/api-key">here</a>.</td></tr></tbody></table>

**Response:**

```json
{
  "success": true,
  "token": "<token string>"
}
```

Use the returned `token` value when initializing the Web Integration Widget on the client side.

### Install the Web Integration

Read more in the [Installation](/integration-options/web-mobile-web/web-integration/installation.md) page

### Use the Web Integration

Read more in the [Usage](/integration-options/web-mobile-web/web-integration/usage.md) page


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://legacy-docs.usesmileid.com/integration-options/web-mobile-web/web-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.