Reconnect an integration

Goal

A connection's access token can no longer be refreshed, so TaskJuice raises a red reauthorization banner and any step that needs that connection fails. This page gets you from that alert back to a working connection and a running workflow: reconnect the integration so its status returns to active, then retry the runs that failed.

When to use this

Reach for this page when you see any of these:

• A red banner at the top of the runs area reading "A connection needs to be reauthorized" (or "N connections need to be reauthorized" when more than one is affected). The banner row is a link titled after the app, for example "Slack reauth required".
• An unread critical notification in the bell, titled after the app that needs attention.
• A run whose step failed because its connection cannot authenticate.
• A connection showing status error with the description "Reconnection needed."

A single transient authentication blip does not require any of this. When a token refresh fails temporarily, TaskJuice retries with backoff and the run continues on its own. The reauthorization alert appears only after a refresh fails permanently, which is the one case where you have to reconnect by hand.

Reconnect the integration

The connection states you will encounter are the four values in the connection status model: active, pending, error, and revoked. A connection in error is the "needs reauthorization" state. Reconnecting flips it back to active.

1. Open the affected connection

   Click the reauthorization banner, or open the notifications bell and click the reauth notification. Both deep-link to your workspace Apps page, where apps with a broken connection are listed first. Open the app and find the connection showing status error. If several apps are affected, the banner names the first and shows how many more remain; work through them one at a time.

2. Reconnect the credential

   Reconnecting re-runs the provider's own OAuth consent flow for that connection. Authorize TaskJuice again at the provider, and the provider issues a fresh token. There is no password to re-enter inside TaskJuice; you grant access on the provider's consent screen, the same way the connection was first authorized.

3. Confirm the status returned to active

   After consent completes, the connection's status changes from error to active. That is the signal the credential is healthy again. If the status does not change, see Troubleshooting below.

When a client owns the connection

If the broken connection belongs to a client (one your client authorized through their portal), the client reconnects it from their own Connections page at /portal/connections. On the connection detail screen they will see the status "Reconnection needed." and two actions:

• Refresh credential re-runs the OAuth token refresh. The success toast reads "Connection refreshed."
• If a refresh is not enough, reconnecting through a fresh request email re-runs the full consent flow.

The client never types a secret into TaskJuice and never sends one over email; authorization always runs through the provider's consent screen. To send a client a reconnection request, see requesting client credentials.

Re-run the failed work

Reconnecting fixes the credential, but it does not restart anything. TaskJuice does not hold a run while a connection is broken: a step that uses the connection fails when it runs, and the run ends as failed. Nothing parks an agent run on reauthorization either, so no run resumes by itself after you reconnect.

To find the affected runs, open the runs list and set Status to Failed, then open each run whose failed step uses the reconnected connection. Once the connection shows active, get the work done in one of these ways:

• Retry the failed run. At the top of the run's page, click Retry from failed step. A new run starts at the step that failed, with the failed run's own data, and the steps that already worked keep their results. To retry several at once, tick the runs in the filtered list and click Retry selected. See Retry a failed run.
• Start a new run from the workflow's runs page. Click the workflow's name in the run page's breadcrumb, then click Run and enter the input as JSON. The dialog starts from an empty {} payload; it does not carry over the failed run's input.
• Start a new run from the workflow editor. On a published workflow, click Run. For a webhook or other push trigger the dialog offers Replay latest event & run, which re-sends only the most recent event the trigger received, not the failed run's own input.
• Wait for the next event. The next trigger event runs the workflow as usual.

Verify it worked

You have fully recovered when all three of these are true:

1. The reauthorization banner is gone and the reauth notification is cleared from the bell. The banner is driven by unread notifications, so it disappears once the alert is resolved.
2. The connection shows status active (a client-owned connection shows the description "Connected and working.").
3. The new runs you start get past the step that failed on the broken connection.

Troubleshooting

Refreshing the connection returns an error instead of reconnecting. A manual refresh against a permanently broken connection returns HTTP 400 with the message "Connection cannot be refreshed. Please reconnect your connection." A refresh only renews an existing token; it cannot recover a credential the provider has rejected. Run the full reconnect (re-authorize through the provider's consent screen) instead of refreshing.

The banner keeps coming back after you reconnect. Each affected connection raises its own reauth notification, and the banner counts all of them. If the banner still shows after you fix one app, another connection is also in error. The banner names the first affected app and, when more than one is affected, shows how many more remain; clear each one in turn.

A run that needed the connection still shows failed after you reconnect. Reconnecting does not retroactively restart a run that already failed, and a retry leaves the failed run as it was. Confirm the connection is now active, then retry the run as described in Re-run the failed work. The work continues in the new run.

You reconnected, but a single auth blip is back the next day. A one-off transient refresh failure is normal and retries automatically; it is not a reason to reconnect. Only a permanent failure raises the reauthorization alert. If you are getting repeated permanent failures on the same connection, the provider may have revoked access at their end (for example, the user changed their password or removed the app), in which case reconnecting through fresh consent is the fix.

Related

• Why a run paused explains every reason a run stops short, including reauthorization and approvals, how each one resumes, and how a reached spend cap stops new runs.
• Run and step statuses defines paused, waiting, error, and every other status value.