Skip to main content

Reconnect an integration

Clear a "needs reauthorization" alert by reconnecting the integration, then resume any runs that paused while its token was broken.

Goal

A connection's access token can no longer be refreshed, so TaskJuice raises a red reauthorization banner and any run that needs that connection stops. 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 resume the runs that paused.

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 Paused for reauth preset chip on the runs list, or a run whose step is parked 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.

What the alert actually means

The reauthorization banner is driven by the unread notifications in your bell. Behind it, the affected connection has moved to status error: TaskJuice tried to refresh its token, the provider rejected the refresh outright, and there is no way to recover the credential automatically. Reconnecting re-runs the provider's consent flow and mints a fresh token.

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 Connections page, where each connection lists its app, label, and status. Find the one 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.

Resume the paused runs

Reconnecting fixes the credential. What happens to the runs that already stopped depends on the kind of run.

  • Agent runs parked on reauthorization resume by themselves. Once the connection is healthy and the reauthorization is consumed, the run returns to running and continues its next step. You do not click anything.
  • Runs an operator paused resume with the Resume button on the run detail page (/{workspaceSlug}/monitoring/workflow-runs/{workflowId}/{runId}). Resume is shown when the run status is paused.

To find runs that stopped for this reason, open the runs list and apply the Paused for reauth preset chip, then open each run and resume it if it is still paused.

Republish or reactivate is not part of this flow

Reconnecting a credential does not republish your workflow. If your workflow was blocked from publishing because a connection was inactive, fix the connection first, then publish. The publish gate enforces this with the error "Trigger node has an inactive connection" or "Action node has an inactive connection". See fix publish errors.

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 previously paused runs are no longer paused. Agent runs have moved back to running on their own; operator-paused runs moved to running after you clicked Resume.

If a run finished as failed rather than pausing, reconnecting alone will not restart it. Replay it once the connection is healthy. See replay and re-run.

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 shows failed, not paused. Reconnecting does not retroactively restart a run that already failed. Open the run, confirm the connection is now active, then replay the run. Replay is only offered for terminal runs (completed, failed, or cancelled). See replay and re-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.

  • Why a run paused explains every reason a run stops short, including reauthorization, approvals, and spend caps, and how each one resumes.
  • Run and step statuses defines paused, waiting, error, and every other status value.
  • Replay and re-run covers restarting a run that failed before you fixed the connection.
Was this helpful?
Why a run paused and how it resumesRe-run a run after you fix it