How can I know which Terra user ID was authenticated by the widget?

When Terra redirects to your site or app, post-auth success, we store the user_id and reference_id in the query parameters of the redirect, so you can get the user_id in sync from the current url (Terra redirects also support deep links and the query paramets should still be accessible)

Alternatively, you can set a reference_id when generating the widget which will also be sent with the auth_success payload and every following payload.

Understood, what would be the ideal authentication flow

The ideal authentication flow using the Terra API would look something like this:

1. The user clicks on Connect Device in your app
2. Your frontend requests your backend for a widget URL
3. Your backend generates a widget url by calling the /auth/generateWidgetSession endpoint. This should be done in the backend as it requires your private API key. Provide a auth_success_redirect_url, something like https://yourapp.com/terra/on_connection_success. You should also supply a reference_id, potetially your internal user-id format e.g USR1234.
4. Redirect to the widget url in your frontend (or if you are developing a mobile app, open the url in the in-app browser)
5. After the user connects their wearable fitness device, the widget will redirect to the auth_success_redirect_url you provided with the query parameters: https://yourapp.com/terra/on_connection_success?user_id=123-abced-456&reference_id=USR1234
6. Then if you wish to fetch an activity for this user, use the user_id to make a GET request