# Handling authentication events

## 1. Handle authentication events

Terra pushes a [Authentication Events ](https://docs.tryterra.co/reference/health-and-fitness-api/event-types#authentication)to your data destination (e.g. Webhook) any time a user has **connected**, **disconnected**, **failed** to **connect**, **reconnected**, or their **access** **was** **revoked**.

These event payloads contain important details such as: `user_id` , auth `status` , and `message`.

Here is an example of a successful `auth` event:

<pre class="language-json" data-title="auth_success" data-line-numbers><code class="lang-json"><strong>{
</strong>    "type": "auth",
    "status": "success",
    "widget_session_id": "a9a0c7a4-c05e-4550-a973-f87a31a7c558",
    "user": {
        "scopes": "COURSE_IMPORT,WORKOUT_IMPORT,ACTIVITY_EXPORT,HEALTH_EXPORT",
        "active": true,
        "last_webhook_update": null,
        "created_at": "2024-10-07T03:45:00.000000+00:00",
        "user_id": "4735eac4-31a2-47ef-8b11-51e98d84c680",
        "reference_id": "tony_stark",
        "provider": "GARMIN"
    },
    "reference_id": "tony_stark",
    "message": "User has successfully authenticated",
    "version": "2022-03-16"
}
</code></pre>

To correctly parse the payloads, review the full list of event formats under [Reference Page > Event Types > Authentication](https://docs.tryterra.co/reference/health-and-fitness-api/event-types#authentication).

You can find **all your received events (payloads)** in:

* Your [Terra Dashboard > Payload History](https://dashboard.tryterra.co/dashboard/debug).

***

## 2. Retrieve User ID

Once your end-user has authenticated their data source, you will receive an [Authentication Event](https://docs.tryterra.co/reference/health-and-fitness-api/event-types#authentication).

Your goal is to obtain a `user_id` from the [Authentication Event](https://docs.tryterra.co/reference/health-and-fitness-api/event-types#authentication) in order to map incoming health data to the correct user in your system. You should save this retrieved `user_id` in your **Database.**

Without this step, you won't be able to associate data events (like activity or sleep) with the right user.

{% hint style="info" %}
The `user_id` will also be in query parameters the final URL of the authentication flow.

The final redirection URL will take the form:

**\`{auth\_success\_redirect\_url}?user\_id=...\&reference\_id=...\&resource=...\`**
{% endhint %}

{% hint style="info" %}

### Does `user_id` change after a re-auth?

Yes. Connecting the same provider a second time with the same `reference_id` and `dev_id` will delete the previous `user` record for that account and yield a new `user_id`. This is per-provider — re-authenticating Fitbit won't affect an Apple Health connection under the same `reference_id`.

The old `user_id` will no longer appear in the Users tab on your Dashboard, though Payload History will still show data that was previously sent to it. When this happens, Terra sends a `user_reauth` event containing both the old and new `user_id`. Make sure you handle this event to update the stored `user_id` in your database, otherwise incoming data won't match your records.
{% 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/handling-authentication-events.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.