# needs_reauth explained: what it means and what to do (/blog/needs-reauth-explained)

![Illustration: A small friendly robot with a round camera-eye head holds up an expired paper ticket at a turnstile.](/blog/needs-reauth-explained/hero.webp)

`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.

**What to do about needs\_reauth**

1. **Recognize it** (tool listed, CoreSpeed key fine, the call fails with needs\_reauth) — Presence is not health. The tools stay in tools/list.
2. **Stop retrying** (the state never clears on its own) — Tell the user which account needs attention and where to go.
3. **Check the account state** (GET /connectors, the account's status field) — Takes an API key or a session JWT. The MCP OAuth token works only on POST /mcp.
4. **Reauthorize** (Dashboard, Connectors, sign in at the provider again) — Done by the member who connected it. Alias, scope and tools are kept.

Your CoreSpeed key and your client config are fine; the break is at the provider grant.

## What does needs\_reauth mean? \[#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](/docs/errors) says.

## Why does it happen? \[#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? \[#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? \[#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:

```bash
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? \[#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](/docs/connectors).

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 \[#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.