> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/unified-api/implementation-custom-ui.md).

# Custom authentication UI

Build your own connect buttons, generate a provider login link from your backend, and open it for the end user.

Use your own UI instead of the Terra widget when you want a button per provider inside your app. Your backend generates a login link for one provider, and the end user goes straight to that provider's login screen.

## 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://docs.tryterra.co/reference/health-and-fitness-api/integrations#get-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/unified-api/setting-up-data-sources.md) (using the `enabled` boolean parameter in the response), along with their associated metadata, such as available **data types**, **display names**, and **logos**.

## Generate an auth link

From your backend, call [`/auth/authenticateUser`](https://docs.tryterra.co/reference/health-and-fitness-api/authentication#post-auth-authenticateuser) to generate an authentication link.

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

{% hint style="info" %}
Apple Health, Health Connect and Samsung Health have no web login. If you have no app of your own, pass `sdk_app: "grip"` to send the user to [Terra Grip](https://docs.tryterra.co/mobile-sdks/terra-grip-companion-app.md).
{% endhint %}

{% 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 '{
      "reference_id": "my_first_connection",
      "auth_success_redirect_url": "https://example.com/success",
      "auth_failure_redirect_url": "https://example.com/failure"
  }'
```

{% endcode %}

See the [API reference](https://docs.tryterra.co/reference/health-and-fitness-api/authentication#post-auth-authenticateuser) for every parameter.

{% hint style="info" %}
Use `reference_id` in your request Body to pass in your own end user's ID on your system.

This will simplify reconciling the terra [User](https://docs.tryterra.co/introduction/core-concepts#users) with your end user.
{% endhint %}

## Read the auth URL

The endpoint will generate an **authentication url** in the response. Retrieve it by parsing `"auth_url"`.

{% 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 %}

## Open the auth URL

Pass the retrieved `"auth_url"` 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://docs.tryterra.co/introduction/core-concepts#sources) 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&amp;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&amp;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/unified-api/setting-up-data-sources.md#choose-data-types)
{% endhint %}

## Avoid common mistakes

{% hint style="danger" %}

* Do not expose your API credentials. Instead, always call the [`/auth`](https://docs.tryterra.co/reference/health-and-fitness-api/authentication#post-auth-authenticateuser) 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.
  {% endhint %}

## Next steps

* [Authentication redirect pages](https://docs.tryterra.co/unified-api/customising-authentication-redirects.md): send the end user back to your app after they connect.
* [Handle the auth event](https://docs.tryterra.co/unified-api/authentication-flow.md#handle-the-auth-event): store the `user_id` Terra sends when the connection succeeds.
* [Health data events](https://docs.tryterra.co/unified-api/receiving-data-updates.md): process the data Terra sends for connected users.
