> 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/faq/help-topics/data-api-sdk/authentication-users-and-connection-state/auth-flow-start.md).

# How do I start user authentication?

There are **two ways to authenticate users**:

{% stepper %}
{% step %}
Generate a [widget session](https://docs.tryterra.co/health-and-fitness-api/user-authentication/implementation-terra-widget) via `generateWidgetSession` and redirect the user to the returned URL, where they pick a provider and are returned with `user_id` and `reference_id`.
{% endstep %}

{% step %}
Call `authenticateUser` with `resource` set to the provider (for example `GARMIN`, `WITHINGS`) and redirect to the returned `auth_url`. See [custom UI implementation](https://docs.tryterra.co/health-and-fitness-api/user-authentication/implementation-custom-ui).
{% endstep %}
{% endstepper %}

Configure your API key, `dev-id`, data destination and data sources in the dashboard first.

Auth tokens from `/auth/generateAuthToken` are mapped to your `dev-id`, are single-use, and expire after 300 seconds. They are not bound to a `reference_id`, so bind the connection by supplying `reference_id` at connection-init time, and keep tokens server-side.

If `authenticateUser` returns `{ message: null }`, your headers are likely swapped: `dev-id` must carry the human-readable developer ID and `x-api-key` the long API key. Correct headers return an `auth_url` field. See the [authentication flow](https://docs.tryterra.co/health-and-fitness-api/user-authentication/authentication-flow).