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:
| State | Meaning |
|---|---|
active | Admitted for use, subject to current tool access and policy |
degraded (healthStatus) | Still active, but credential renewal has repeatedly failed |
reconnect_required | Fresh user consent or credentials are needed |
revoking | Local use stopped; provider retirement is still in progress |
revoked | Connection 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.

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.

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.

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.


