Read connected account state through its full lifecycle
Interpret provider status, owner verification, reconnect replacement and upstream revocation as distinct lifecycle stages.
Recover a connection after provider authorization stops working
Distinguish inactive grants, insufficient scope and provider outages while preserving the replacement authorization lifecycle.
Refresh state before assuming token expiry
A failed app action can result from revoked consent, an inactive provider account, insufficient scope, an app outage or changed toolkit metadata. Read the connection state first and preserve the original tool operation ID. Lupin checks active status and ownership before executing and returns connection_not_active when the account cannot be used. That code points toward authorization recovery; a generic provider failure does not prove token expiry. Avoid asking the owner to reconnect repeatedly until the error disappears, because each attempt creates lifecycle work and may consume capacity or usage.
Keep OAuth secrets inside the hosted flow
Composio manages provider OAuth credentials for the connection. The owner should not export a refresh token, paste a password into an agent chat or replace server-side credential fields in tool arguments. Lupin’s execution endpoint accepts only the discovered version, account revision and approved arguments. If authorization needs repair, use the supported reconnect path under an organization credential with api_key_create. Before starting, confirm that the app remains operator-enabled and that the account owner is available to review the hosted provider permissions and identity.
Start one deliberate replacement attempt
POST /v0/connections/:connection_id/reconnect requires a preserved Idempotency-Key. Save the attempt identity before requesting the hosted link. Lupin keeps the old account registered while replacement authorization is pending and prevents a second reconnect from obscuring the unfinished attempt. The owner completes authorize_url and then refreshes the connection list for authoritative provider status. A browser return parameter does not prove activation. If the response is uncertain, retain the same key and operation ID instead of starting another replacement with a new key.
Rediscover tools and obtain fresh approval
A replacement account can change identity or scopes while retaining the local connection ID. Its revision changes, so approvals tied to the previous account must not execute. Once the new account is active, discover tools again, inspect the schema and concrete version, and present the exact action for approval. Do not automatically replay the action that originally failed if the provider outcome was uncertain. Separate reconnect recovery from action reconciliation: restoring authorization does not establish whether an earlier tool already created an issue, sent a message or changed external state.
Escalate persistent uncertainty with narrow evidence
Provide support with the connection ID, lifecycle operation ID, observed status and sanitized failure phase, keeping provider identifiers private where appropriate. A reconciliation_required response means the durable operation needs investigation before another attempt. Preserve the registry and any lifecycle lock; deleting local records can hide a still-authorized provider account. After recovery, verify the intended account and a reviewed schema before resuming work. A useful regression simulates revoked authorization, pending replacement and active replacement, checking that stale approvals fail and no duplicated external action is issued during the transition.
Keep the earlier action unresolved until proven
If authorization fails after an issue-creation timeout, restoring the account does not establish whether the issue exists. Reconcile the original operation before proposing another creation. This case belongs in the recovery checklist because a helpful reconnect assistant can otherwise restore access and immediately duplicate the action the owner was trying to repair.
Sources & verification
Reviewed against current checked-in Lupin routes, shared contracts and official provider references. No live calls, OAuth authorizations, app actions or purchases were performed.
- Lupin connections Checked 2026-11-05
- Composio hosted account link API Checked 2026-11-05
- Composio authenticating tools Checked 2026-11-05
Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.