Skip to content

Reauthorizing Connections in an Integrated Account

Sometimes, you may need to refresh your connection to an integration in Truto. This could be because of changes to your integration settings or updates in the integration itself. Reauthorizing your connection will allow the integration to continue to work properly with the updated information.

Getting notified about reauthorization

In case of OAuth integrations, when an end-user revokes access for the OAuth app, Truto will not be able to refresh the access tokens. In such cases, when Truto fails to refresh the access token, it marks the integrated account needs_reauth and sends an integrated_account:authentication_error event with the integrated account as the payload. The event is sent once, when the account moves into needs_reauth; further failures while it stays in that state send nothing. When the account recovers, Truto sets it back to active and sends integrated_account:reactivated. You can use this event to notify the end-user about the issue and ask them to re-authorize the connection.

For OAuth with refresh token functionality, the account moves to needs_reauth (and the integrated_account:authentication_error event is sent) when there is an issue with refreshing the access token for an integrated account regardless of what the underlying issue is.

For other authentication methods and OAuth without refresh token functionality, the account moves to needs_reauth when an underlying API call to the integration fails with a 401 response status code. This can happen when proxy and unified APIs are called, or when Sync Jobs are run.

Webhooks Guide

Reauthorize Connections via Truto interface

Follow these simple steps:

  1. Sign into Truto and go to the Integrated Accounts section or click here. Select an Integrated account
  2. Select an Integrated Account. On the account detail page, click Re-authorize connection. Re-authorize connection
  3. In the dialog, click Get connection link. Get connection link
  4. Open the Magic Link to complete re-authorization. You can share this link with your customer instead. Complete re-authorization

What happens next?

After clicking on the Magic Link, you will be redirected to your account on the integrated platform. You will have to log in and allow access to Truto. Follow the steps for authentication, and upon successful completion, you will see a 'Connection successful' message. You can then close the tab.

Reauthorizing an account via API

Use the following cURL command to generate a link-token. Truto uses Bearer authorization, replace the <your-api-token> in the command below with your API token.

Create Link Token API Reference

curl --location 'https://api.truto.one/link-token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-api-token>' \
--data '{
    "integrated_account_id": "<integrated-account-id>"
}'

Response:

{
    "link_token": "e73c7b9b-2e4d-47d1-b5d2-83441fd24e4c"
}

Use the following URL, to launch Truto's connection UI. Remember to replace <link-token-from-previous-step> with the actual link token received from the API request.

https://app.truto.one/connect-account?link_token=<link-token-from-previous-step>

When the token is refused

Reauthorization may switch sign-in method: the connection UI offers whatever methods the integration still has, and the account's authentication_method is updated when the end user picks a different one. So the token is refused only when nothing on the integration can connect — every method it has is a bring-your-own-app one (OAuth 2.0 or AWS STS) whose app credentials have been removed from this environment since the account connected. Then no token is created and the API answers 400 with truto_error_code: "app_credentials_not_configured"; the body also carries integration, environment_integration_id and authentication_methods. Add the credentials back (or enable another method) and retry; nothing the end user does can complete the reauthorization until then. An account on an integration that still has a working method — an API key beside an unconfigured OAuth app, say — gets its token as usual and reconnects with that method.

Embedding the linking flow within your app

You can also use our Frontend Link SDK to embed the connection flow within your UI. More details here.

With this, your Re-authorization process is complete! You've now ensured that your Truto integration will continue to work properly, even with the updated information.