> 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/user-authentication.md).

# User authentication

Securely connect your users' health data sources to your application via Terra.

User authentication allows Terra to accessing your users' health and fitness data and is essential to using the Unified API.

Authentication allows your end-users to grant your application permission to retrieve data from their wearables or fitness platforms (like Fitbit, Garmin, Oura, etc.). Once a user is successfully authenticated, Terra automatically pushes their health data events to your configured destination.

***

## Implementation guides

{% stepper %}
{% step %}
[**Authentication flow overview**](/unified-api/user-authentication/authentication-flow.md)

Get an overview of the user authentication process, from the initial user action in your app to receiving their Terra User ID.
{% endstep %}

{% step %}
[**Authenticating with the Terra widget**](/unified-api/user-authentication/implementation-terra-widget.md)

The quickest way to get started. Learn how to integrate Terra's pre-built, customisable UI to handle the provider selection and authentication process with a single API call.
{% endstep %}

{% step %}
[**Handling authentication events**](/unified-api/user-authentication/handling-authentication-events.md)

Understand the different types of authentication events Terra sends (success, failure, deauthorisation) and how to process their payloads effectively.
{% endstep %}
{% endstepper %}

***

## Configuration

[**Customising authentication redirects**](/unified-api/user-authentication/customising-authentication-redirects.md)

* Learn how to customise the <mark style="color:green;">success</mark> or <mark style="color:red;">failure</mark> screen that users see after they complete the authentication flow but before they are redirected back to your app.

[**Authenticating with your own UI**](/unified-api/user-authentication/implementation-custom-ui.md)

* For maximum control over the user experience. This guide details how to build your own device connection screen and use Terra's API to authenticate users with specific providers.

{% hint style="info" %}
💡 **Pro-Tip:** Start with the widget because it’s the:

1. **Fastest way to go live:** no need to build or maintain your own auth UI
2. **Easiest to implement:** just one backend call to generate the link
3. **Optimized UX:** designed and tested for high end-user completion rates across devices and platforms
   {% endhint %}

***

## ✅ Checklist

{% hint style="success" %}

### Implementing the User Authentication in your App

1. **API**:
   1. **Credentials:** Did you find your Terra API Keys and Dev-ID in your Terra Dashboard?
   2. **Endpoint**: Did you make a **successful** **request** from your backend to one of the /auth endpoints?
      1. <mark style="color:orange;">`POST`</mark> `/api/widget/session` (the Terra widget; existing integrations may still be on `/auth/generateWidgetSession`)
      2. <mark style="color:orange;">`POST`</mark> `/auth/authenticateUser?resource=oura`
   3. **Response**: Did you get a **successful response** (`201` from the widget endpoint, `200` from authenticateUser) and parse the authentication url? Either:
      1. `"url"`: the widget screen (via the widget endpoint)
      2. `"auth_url"` : the provider's login screen (via the authenticateUser endpoint)
   4. **End-user:** Was your end-user redirected to an **Auth** **Success** **Screen**?
2. **Event**: Did you receive an **Success "Authentication Event"** to your destination?
3. **Database**: Did you save this user in your Database using `user_id` ?
   {% endhint %}