Implementation (Terra widget)
1. Make an API Request
Make an API Request to the /auth/generateWidgetSession
endpoint from your backend.
curl --request POST --url https://api.tryterra.co/v2/auth/generateWidgetSession \
--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",
}'
2. Parse the Widget URL from the JSON Response
The endpoint will generate a widget url in the response. Retrieve it by parsing "url"
.
{
"session_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
"url": "https://widget.tryterra.co/session/344d475f-296a-489a-a88c-54183671dafd",
"status": "success",
"expires_in": 900
}
3. Open The Widget URL
Pass the retrieved "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 your end user to the provider selection screen, the Terra authentication widget.



You can find a list of all your authenticated users in:
Or by using the /subscriptions endpoints
❌ 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.
Last updated
Was this helpful?