Implementation (Custom UI)

1. Build your UI

First, create a button for each data source that a user might want to connect. (e.g. a "Connect to Fitbit" button). You may take inspiration from the Terra Widget when creating your own UI.

You may use the /integrations/detailed endpoint to fetch metadata for each source available through Terra when creating your UI. This enables you to dynamically retrieve the sources you’ve activated in your Dashboard (using the enabled boolean parameter in the response), along with their associated metadata, such as available data types, display names, and logos.

---

2. Make an API Request

From your backend, call the /auth/authenticateUser to generate an authentication link

Use the parameter resource to pass a source name (e.g. "oura" , "withings" ..)

Command Line

curl --request POST --url https://api.tryterra.co/v2/auth/authenticateUser?resource=oura \
  --header 'dev-id: <YOUR-DEV-ID>' \
  --header 'x-api-key: <YOUR-API-KEY> \
  --header 'Content-Type: application/json' \
  --data '{
      "language": "en",
      "reference_id": "my_first_connection",
      "auth_success_redirect_url": "text",
      "auth_failure_redirect_url": "text"
  }'

See details in the API Reference Page.

Pro tip: Use reference_id in your request Body to pass in your own end user's ID on your system.

This will simplify reconciling the terra User with your end user.

---

3. Parse the Auth URL from the JSON Response

The endpoint will generate an authentication url in the response. Retrieve it by parsing "auth_url" .

JSON

{
  "status": "success",
  "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
  "auth_url": "https://cloud.ouraring.com/oauth/authorize?response_type=code&client_id=...&redirect_uri=https%3A%2F%2Fapi.tryterra.co%2Fv2%2Fauth%2Foura%2Foauth2&scope=email+spo2+session+heartrate+personal+daily+workout+tag.."
}

---

4. Open The Auth URL

Pass the retrieved "auth_url" to your client side, and open it either in:

• an in-app browser, if using a mobile app,

• or a new tab, if using a web app

This will take the user straight to the data source's login screen so they can connect it.

Login Screen (example: Oura)

Permission screen (example: Oura)

The permissions list can be customised through your Terra Dashboard

---

❌ Common Mistakes

Common Mistakes and Best Practices

• Do not expose your API credentials. Instead, always call the /auth endpoints from your backend.

• Do not call the API from your frontend, as this will lead to a CORS error.

• Do not use WebView or iFrame for the authentication flow. Using them poses security risks due to the invisible URL bar, meaning that the user cannot know the domain onto which they are entering their username & password. Providers may completely block authentication leading to an error during the flow. Instead, use a new tab or an in-app browser to open the URL returned by the /auth endpoints.