Connections

Connection statuses, refreshing tokens, reconnecting a broken connection, and revoking one for good.

A connection is one user's authorized account in one app — one row on their Connections tab, and one thing that can go stale, get revoked, or need a fresh grant.

Statuses

The API returns connection status and a separate healthStatus. Current states include:

StateMeaning
activeAdmitted for use, subject to current tool access and policy
degraded (healthStatus)Still active, but credential renewal has repeatedly failed
reconnect_requiredFresh user consent or credentials are needed
revokingLocal use stopped; provider retirement is still in progress
revokedConnection retired

Use returned state, not a screenshot label, to decide whether to offer reconnect or show cleanup in progress. The screenshots below illustrate the dashboard presentation.

Samantha Harris's Connections tab with one connection showing Expired status
An expired connection — the refresh token is dead.

Token refresh

Arc0 manages supported token refresh and renewal, tracks failures and retries transient failures with backoff. A connection requiring new consent must be reconnected; retrying a refresh does not repair a revoked grant.

There is no public force-refresh endpoint. Arc0 manages refresh automatically; use the dashboard for an authorized manual retry.

Connection details

Expanding a row shows two panels. Scopes lists every requested scope, each marked Granted, Declined, or Not requested. Token shows Connection, Connected, Access token, Last refreshed, and OAuth client — either "Arc0's verified app" or the client id, depending on whether the project uses its own OAuth app. Refresh now and Revoke sit at the bottom of the panel.

An expanded connection row showing its granted scopes and token details
A connection's scopes and token details, expanded.

Reconnecting

When a connection needs attention, create a fresh hosted Connect link for its owner. The current link is single-use and lasts 10 minutes. This is a hosted consent flow; the application should confirm connection state after the user finishes.

The Reconnect dialog for a broken connection, with a Send to field and the generated Arc0 Connect link
The reconnect dialog.

Use POST /v1/connect with {app, endUserId, reconnectConnectionId, authMethod}. reconnectConnectionId is the existing connection's internal ID; use its original app and supported authentication method. The response is {url}. Resolve the user from your backend session and check connection ownership; never accept an arbitrary browser-selected subject.

Revoking

Use POST /v1/connections/:id/revoke with {endUserId} and a server-held Embedded management key with connections:manage. Check ownership in your application first. The response is {ok: true}. Local execution access stops while provider token retirement may continue asynchronously. Read GET /v1/connections?endUserId=... to inspect state; revoking is not proof that provider cleanup has completed.

On this page