# Implementation (Terra widget)

## 1. Make an API Request 

Make an API Request to the [`/auth/generateWidgetSession`](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/health-and-fitness-api/readme#post-auth-generatewidgetsession) endpoint from your backend.

{% code title="Command Line" %}

```bash
curl --request POST --url https://api.tryterra.co/v2/auth/generateWidgetSession \
  --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 %}

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

***

## 2. Parse the Widget URL from the JSON Response

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

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

```json
{
   "session_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
   "url": "https://widget.tryterra.co/session/344d475f-296a-489a-a88c-54183671dafd",
   "status": "success",
   "expires_in": 900
}
```

{% endcode %}

***

## 3. Open The Widget URL

Pass the retrieved <mark style="color:purple;">`"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 your [end user](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/health-and-fitness-api/core-concepts#end-user) to the provider selection screen, the Terra authentication widget.

<div><figure><img src="https://464213908-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVGMJVuZnZyOtvV4b53cY%2Fuploads%2FCZcrIrTlh3Br1VHBtS7s%2Fwidget.png?alt=media&#x26;token=591ee25e-2aa7-47ff-ba68-e88b893db3c9" alt="" width="188"><figcaption><p><strong>Device</strong> S<strong>election</strong> screen <br>(Terra authentication widget)</p></figcaption></figure> <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 %}

You can find a list of all your **authenticated** **users** in:

* Your [Terra Dashboard > Users](https://dashboard.tryterra.co/dashboard/users)
* Or by using [the /subscriptions endpoints](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/)

***

## ❌ Common Mistakes

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