Handling authentication events

1. Handle authentication events

Terra pushes a Authentication Events 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:

auth_success

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

To correctly parse the payloads, review the full list of event formats under Reference Page > Event Types > Authentication.

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

• Your Terra Dashboard > Payload History.

---

2. Retrieve User ID

Once your end-user has authenticated their data source, you will receive an Authentication Event.

Your goal is to obtain a user_id from the Authentication Event 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.

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=...`

Does user_id change after a re-auth?

Yes. Connecting an account (i.e. User) a second time on the same dev_id will delete the previous user record for that account, and yield a new user_id