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. How the account recovers decides which events you get. If a later token refresh succeeds, Truto sets the account back to active and sends integrated_account:reactivated. If the end user reconnects the account, Truto sends integrated_account:updated, followed by integrated_account:active once post install and validation steps pass. 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

Keeping existing variables

By default, a reauthorization replaces the account's variables with what the new connection produces: the credentials the end user enters (or the new OAuth token) plus any context you set on the link token. Everything else stored on the account is dropped, including:

  • variables you added on the account's Variables section or through the API,
  • the choices the end user made in a RapidForm,
  • the drive_items saved by the Link SDK's native file pickers.

To keep them, create the link token with persist_previous_context: true. The account's existing variables are kept and the reconnection's values are layered on top, so a variable with the same name is overwritten by the new value.

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>",
    "persist_previous_context": true
}'

In the Truto interface, the same option is the Persist existing variables checkbox under Advanced settings in the reauthorize dialog. It is off by default in both places.

Stale accounts

An account that stays needs_reauth, with no change, for 7 days becomes stale: Truto stops calling the provider for it, and its API calls get a 401 with truto_error_code: integrated_account_needs_reauth, until it is reconnected. Reconnecting it as described below ends the pause. See Stale integrated accounts for what stops, how you find out, and the other ways to end the pause.

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. To keep the account's current variables, first open Advanced settings and check Persist existing variables (see Keeping existing variables). 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.