# User authentication

User authentication allows Terra to accessing your users' health and fitness data and is essential to using the Health & Fitness 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**](/health-and-fitness-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**](/health-and-fitness-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**](/health-and-fitness-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**](/health-and-fitness-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**](/health-and-fitness-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> `/auth/generateWidgetSession`
      2. <mark style="color:orange;">`POST`</mark> `/auth/authenticateUser?resource=oura`
   3. **Response**: Did you get a **200 response** 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tryterra.co/health-and-fitness-api/user-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.