needs_reauth explained: what it means and what to do
needs_reauth means an account's upstream grant can no longer be used. Tools stay visible, calls fail, and the fix is reauthorizing in the dashboard.
needs_reauth is the state of one connected account whose upstream OAuth grant CoreSpeed can no longer use. The connector stays known, its tools stay in tools/list, and every call through that account fails until the member who connected it reauthorizes in Dashboard → Connectors. Your CoreSpeed key and your client configuration are fine.
- 1Recognize ittool listed, CoreSpeed key fine, the call fails with needs_reauthPresence is not health. The tools stay in tools/list.
- 2Stop retryingthe state never clears on its ownTell the user which account needs attention and where to go.
- 3Check the account stateGET /connectors, the account's status fieldTakes an API key or a session JWT. The MCP OAuth token works only on POST /mcp.
- 4ReauthorizeDashboard, Connectors, sign in at the provider againDone by the member who connected it. Alias, scope and tools are kept.
What does needs_reauth mean?
When you connect an app, CoreSpeed stores the provider's credential and refreshes it when the provider allows. The agent receives tools, never the token. needs_reauth is the moment that refresh stops working: the provider no longer honors the grant, so CoreSpeed cannot act through that account. The account record survives, the tools stay listed, and the state is recoverable. A single sign-in at the provider puts a fresh grant in custody and the same tools start working again.
Two things do not change. The CoreSpeed credential your agent uses to reach /mcp is still valid, and the mcpServers entry in your client is still correct. Rotating the key or rewriting the config wastes time and fixes nothing, as the error handling page says.
Why does it happen?
The common path is on the provider's side: the grant was revoked, expired past what the provider lets CoreSpeed refresh, or invalidated by a change at the provider. There is one path on the CoreSpeed side, and it only touches organizations that brought their own OAuth app. If an org admin replaces that app's client_id or deletes the app, every connection made through it moves to needs_reauth at once, because the grants belonged to the old app.
A connector that takes a pasted API key can reach needs_reauth too, but only when the vendor names the credential itself with a standard code: invalid_token, invalid_client, or invalid_grant. A rejected call on its own does not change the connection's status. For a key connection, reauthorizing means reconnecting: paste the new key and the connection updates in place.
How do you tell it apart from other failures?
| What you see | Meaning | Who fixes it |
|---|---|---|
Tool present, call fails with needs_reauth | The account's upstream grant is unusable | The member who connected it, in Dashboard → Connectors |
401 invalid_api_key on every call | The CoreSpeed key is unknown, revoked or expired | The client: replace the key |
200 with isError, code jwt_session_required | A manage__* tool needs a member session | The client: use a signed-in client |
ambiguous_account | Several accounts of this connector are in scope | The agent: pass account |
not_configured | This environment lacks an app registration | Support |
Tool absent from tools/list | Capability off, or app not connected for this caller | An org admin or the member |
The first row is the only one where the tool is visible, the credential is fine, and the call still fails. That combination is the signature of needs_reauth.
What should the agent do?
Stop retrying. A state of this kind does not clear on its own, and a loop of failed calls helps nobody. Tell the user which account needs attention and where to go. If you want certainty before you report, read the account state from the connector index, which is the only inventory of accounts and their status:
curl https://api.corespeed.io/connectors -H "Authorization: Bearer $CORESPEED_API_KEY"The account's status field says needs_reauth. Note that an MCP OAuth token from browser sign-in works only on POST /mcp; use an API key or a session JWT for this route. If the task can proceed without that account, proceed and leave the blocked step for the person.
What should the person do?
Open Dashboard → Connectors, find the account marked for reauthorization, and sign in at the provider again. The consent screen names CoreSpeed. The connection keeps its alias, its private or shared scope, and its place in tools/list, so nothing on the agent side changes.
Who can do this follows who owns the connection. A private connection is reauthorized by the member who made it. A shared connection is reauthorized by the member who connected it. An organization integration, such as the Slack workspace bot or Linear's app under the alias corespeed-bot, is connected and reconnected by an org admin. The scope rules are on the connectors page.
For an organization that brought its own OAuth app, one more step applies after replacing the app: every member reauthorizes, because every grant moved at once. Plan the replacement for a quiet hour and tell the team before you click.
FAQ
Will the tool disappear from tools/list while the account is in needs_reauth? No. Presence is not health. The tool stays listed and the call fails until the account is reauthorized.
Does reauthorizing create a second account? No. The existing account gets a fresh grant and keeps its alias and scope.
Can an agent reauthorize for me? No. Reauthorization is a browser sign-in at the provider by a member. An agent can tell you which account needs it.
Can I disconnect instead? Yes. Disconnect deletes CoreSpeed's copy of the credential and removes the account's tools. The provider-side grant is yours to revoke in the provider's own settings.