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