# Implementation (Custom UI)

## 1. Build your UI

First, create a **button** for each data source that a user might want to connect. (e.g. a "Connect to Fitbit" button). You may take inspiration from the Terra Widget when creating your own UI.

You may use the [/integrations/detailed](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/health-and-fitness-api/readme#integrations-detailed) endpoint to fetch metadata for each source available through Terra when creating your UI. This enables you to dynamically retrieve the sources you’ve [activated in your Dashboard](https://docs.tryterra.co/health-and-fitness-api/integration-setup) (using the `enabled` boolean parameter in the response), along with their associated metadata, such as available **data** **types**, **display** **names**, and **logos**.

***

## 2. Make an API Request 

From your backend, call the [`/auth/authenticateUser`](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/health-and-fitness-api/readme#auth-authenticateuser) to generate an authentication link

Use the parameter `resource` to pass a source name (e.g. `"oura"` , `"withings"` ..)

{% code title="Command Line" %}

```bash
curl --request POST --url https://api.tryterra.co/v2/auth/authenticateUser?resource=oura \
  --header 'dev-id: <YOUR-DEV-ID>' \
  --header 'x-api-key: <YOUR-API-KEY> \
  --header 'Content-Type: application/json' \
  --data '{
      "language": "en",
      "reference_id": "my_first_connection",
      "auth_success_redirect_url": "text",
      "auth_failure_redirect_url": "text"
  }'
```

{% endcode %}

See details in the [API Reference Page.](https://docs.tryterra.co/reference#auth-generatewidgetsession)

{% hint style="info" %}
**Pro** **tip**: Use <mark style="color:green;">`reference_id`</mark> in your request Body to pass in your own end user's ID on your system.

This will simplify reconciling the terra [User](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/health-and-fitness-api/core-concepts#user) with your end user.
{% endhint %}

***

## 3. Parse the Auth URL from the JSON Response

The endpoint will generate an **authentication url** in the response. Retrieve it by parsing <mark style="color:purple;">`"auth_url"`</mark> .

{% code title="JSON" lineNumbers="true" %}

```json
{
  "status": "success",
  "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
  "auth_url": "https://cloud.ouraring.com/oauth/authorize?response_type=code&client_id=...&redirect_uri=https%3A%2F%2Fapi.tryterra.co%2Fv2%2Fauth%2Foura%2Foauth2&scope=email+spo2+session+heartrate+personal+daily+workout+tag.."
}
```

{% endcode %}

***

## 4. Open The Auth URL

Pass the retrieved <mark style="color:purple;">`"auth_url"`</mark> to your client side, and open it either in:

* an **in-app browser**, if using a mobile app,
* or a **new tab,** if using a web app

This will take the user straight to the [data source's](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/health-and-fitness-api/core-concepts#source-provider-integration) login screen so they can connect it.

<div><figure><img src="https://464213908-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVGMJVuZnZyOtvV4b53cY%2Fuploads%2FTuSK9MXKw4AOlEQWhIWb%2Fscreenshot%20(2).png?alt=media&#x26;token=7ed5038d-471a-4ed7-9818-ea18bb722364" alt="" width="182"><figcaption><p><strong>Login</strong> Screen <br>(example: Oura)</p></figcaption></figure> <figure><img src="https://464213908-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVGMJVuZnZyOtvV4b53cY%2Fuploads%2F1lAow8Zfl010xLxwpRUI%2Fscreenshot%20(3).png?alt=media&#x26;token=36da4b9e-bd6d-495f-b0bb-bf70302d8574" alt="" width="182"><figcaption><p><strong>Permission</strong> screen <br>(example: Oura)</p></figcaption></figure></div>

{% hint style="info" %}
The permissions list can be [customised through your Terra Dashboard](https://docs.tryterra.co/health-and-fitness-api/integration-setup/customising-data-types)&#x20;
{% endhint %}

***

## ❌ Common Mistakes&#x20;

{% hint style="danger" %}

## Common Mistakes and Best Practices

* Do not expose your API credentials. Instead, always call the [`/auth`](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/) endpoints from your **backend.**
* Do not call the API from your **frontend**, as this will lead to a **CORS error.**
* Do not use **WebView** or **iFrame** for the authentication flow. Using them poses security risks due to the invisible URL bar, meaning that the user cannot know the domain onto which they are entering their username & password. Providers may completely block authentication leading to an error during the flow. Instead, use a **new tab** or an **in-app browser** to open the URL returned by the `/auth` endpoints.&#x20;
  {% endhint %}