> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting started with Smart UI
> Learn how to integrate the Smart UI widget in your application."
## Before you begin
You will need the following to connect to the FrankieOne API,
* Customer ID
* Customer Child ID (Optional)
* API key
If you don't have any yet [get in touch with our sales team ](https://frankieone.com/).
You must host Smart UI on your own webserver. FrankieOne doesn't provide a hosted version yet.
**Supported Countries**
Below is a list of countries that are fully supported by the smart UI.
* Australia
* New Zealand
* Indonesia
* Thailand
* Singapore Manual Input (not Singpass)
* Generic International Passport
* Generic International National ID
Future supported countries
* USA
* UK
* All Others
## Step 1: Create a session
Obtain a session on your backend and forward it to your frontend web page.
### Construct the API credential
1. Serialize your FrankieOne API credentials to a string using ':' as a separator.
2. Encode the resulting string using Base64 encoding.
If you are using a macOS or Linux operating system, run the following command in a terminal:
```shell Shell theme={null}
echo -n 'CUSTOMER_ID:API_KEY' | openssl base64
```
If you have a child account with FrankieOne, modify the above command to the following:
```shell Shell theme={null}
echo -n 'CUSTOMER_ID:CUSTOMER_CHILD_ID:API_KEY' | openssl base64
```
### Obtain a temporary session token
Send a `POST` request to the `/auth/v2/machine-session` endpoint.
[](https://god.gw.postman.com/run-collection/fdeb99be92c72a36e5bb)
#### Base URL
Use one of the following base URLs depending on the environment you are targeting. *Note, Smart UI uses different URLs to FrankieOne's server-side APIs.*
| Environment | Base URL |
| :---------: | :---------------------------------------------------------------------------------------------------------------------------------------------------: |
| Demo | [https://backend.demo.frankiefinancial.io ](https://backend.demo.frankiefinancial.io) |
| UAT | [https://backend.kycaml.uat.frankiefinancial.io ](https://backend.kycaml.uat.frankiefinancial.io) |
| Production | [https://backend.kycaml.frankiefinancial.io ](https://backend.kycaml.frankiefinancial.io) |
#### Authorization header
Pass the encoded credential in the `Authorization` request header using `machine` as the scheme:
`Authorization: machine YOUR_ENCODED_CREDENTIAL`
#### Request body
Include the following parameters in the body of the request:
| Parameter name | Required | Description |
| :---------------------: | :--------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `referrer` | Required | A referrer URL pattern used to verify the webpage that Smart UI is hosted on. See [CSP and Smart UI Security Recommendations](/docs/v1/onesdk/Smart-ui-for-deprecation/security-recommendations). |
| `permissions` | Required | A hash containing `preset` and `reference`. |
| `permissions.preset` | Required | The string `"smart-ui"`. |
| `permissions.reference` | Required\* | A string containing your customer reference for the individual being onboarded. Only required if entityId isn't provided |
| `permissions.entityId` | Required\* | A string containing the entity id if the entity exists previously. Only required if reference isn't provided. |
**\* Only provide either reference or entityId, not both.**
##### Note
Applicant Reference with whitespace characters aren't supported by the Smart UI and will be rejected. Let us know if this will prevent you from integrating.
#### Request example
The following example creates a session object for a user in the Demo environment:
```shell Shell theme={null}
ENCODED_CREDENTIAL=$(echo -ne "$YOUR_CUSTOMER_ID:$API_KEY" | base64);
curl https://backend.demo.frankiefinancial.io/auth/v2/machine-session \
-X POST \
-H 'Authorization: machine ENCODED_CREDENTIAL'
-H 'Content-Type: application/json' \
-d '{
"permissions": {
"preset": "smart-ui",
"reference": "YOUR_CUSTOMER_REFERENCE"
}
}';
```
Your `Customer ID` and `API Key` are both secret information and shouldn't be included in the frontend code. For that reason, make sure to call the `/auth/v2/machine-session` endpoint from your backend server.
The `/auth/v2/machine-session` endpoint will respond with a 200 HTTP status code, indicating the session was created successfully.
The response body will include a configuration object that's used by Smart UI to customize its behavior. The configuration object includes a dictionary of strings that might seem like error messages, but they aren't. You may ignore anything found in the successful response body.
### Read the token from the response
The successful response will contain a response header named `token` that contains the authentication token required to configure Smart UI. *This token is valid for only one hour, and within the Smart UI, it's refreshed for another hour on each successful call to the backend server.*
The following example reads the token from the response:
```javascript JavaScript theme={null}
const res = await fetch(
"https://backend.demo.frankiefinancial.io/auth/v2/machine-session",
{
method: "post",
headers: {
"Content-Type": "application-json",
Authorization: "machine ENCODED_CREDENTIAL",
},
body: JSON.stringify({
permissions: {
preset: "smart-ui",
reference: "YOUR_CUSTOMER_REFERENCE",
},
}),
},
);
const smartUIAuthToken = res.headers.get("token");
```
Make sure to access the header by name `token` rather an numeric index, as the order in which the response headers are returned isn't guaranteed to be the same for each request.
## Step 2: Set up Smart UI
### Install the Smart UI widget
Include the Smart UI script tag within the `` section of your HTML page.
```html theme={null}