# Tilia Hosted Widget

This style of integration involves sending the user to the Tilia flow via a full page navigation from your domain to Tilia’s, where Tilia wraps the widget.

Please refer to the [Tilia Hosted Checkout](/web-uis/tilia-hosted-checkout) guide for steps to integrate the checkout flow using this method.

This integration method involves the following steps:

1. User authorization
2. Optionally, return the user to your UI


## User Authorization

To generate a link for the user so that they can access the Tilia flow UI, first you will need to authorize them. POST a request to authorize the user by using an access token with the scope `write_user_tokens`.


```
curl --location --request POST 'https://auth.tilia-inc.com/authorize/user' \
--header 'Authorization: Bearer CLIENT_CREDENTIALS_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
```

### Request Body


```json
{
    "account_id": "<ACCOUNT_ID>",
    "mechanism": "tilia_hosted",
    "flow": "<FLOW_NAME>"
}
```

Where `<FLOW_NAME>` can be  `kyc`, `payout`, `txnhistory`, or `addcard`

### Example Response


```json
{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "nonce_auth_id": "133fafce-80ab-42f6-82b1-7266d9bab91d",
        "redirect": "https://pub.tilia-inc.com/testpublisher/txnhistory/133fafce-80ab-42f6-82b1-7266d9bab91d"
    }
}
```

## Return URL

You can optionally redirect users back to your UI upon completion of the flow by appending `“?returnUrl=<RETURN_URL>”` to the end of the redirect link.

If you wish to provide a return URL, please contact Tilia to help you configure your Allowed Domain Origin List. Any URL provided will fail to redirect unless the domain is provided in the whitelist.

### Redirect Example


```
https://pub.tilia-inc.com/testpublisher/txnhistory/133fafce-80ab-42f6-82b1-7266d9bab91d?returnUrl=https://acme.com
```

Upon completing the flow, the user is redirected to `<RETURN_URL>`, with flow-specific parameters appended.

### Return Example


```
https://acme.com/?source=tilia&event=tilia.txnhistory.complete&state=complete&trigger=header-close-button
```

Refer to the flow-specific documentation for details on the parameters returned.

## Customization

The appearance of the page that hosts the widget can be customized with:

- A background color
- A primary color
- Your brand logo
- Preview text
- Message on complete
- Message on user-cancellation


Contact us for help with the customization of the Tilia Hosted Widget page.