Skip to main content

Documentation Index

Fetch the complete documentation index at: https://authsome.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

A request through the proxy or via an exported token came back with an auth error. Walk this decision tree to recover.

​
First, check provider state

authsome list
This shows every provider, every named connection, and the current state (available, configured, connected).

​
401 Unauthorized

The stored credential is no longer valid. The access token expired and no usable refresh token remains, or the provider revoked the session server-side.
  1. Revoke the current connection so authsome drops the broken record: 
    authsome revoke <provider>
  2. Log in again: 
    authsome login <provider>
If you’re running an agent and the request 401s mid-flight, re-run the same agent command after re-login. The proxy picks up the fresh token automatically.

​
403 Forbidden (missing scopes)

The stored credential is valid, but the request requires permissions the original login did not grant.
Do not register a new provider definition just to add scopes. The existing provider already supports --scopes at login time. Re-registering creates a duplicate definition and an inconsistent state.
Use --scopes on the existing provider: 
authsome login github --scopes repo,user,gist
The list of valid scopes is service-specific. See the provider’s developer docs for the canonical list, or authsome inspect <provider> to see which scopes are declared in the provider definition.

​
Wrong stored client_id / client_secret

If login itself fails immediately with a credential mismatch error and you suspect the wrong OAuth app credentials were stored, remove the provider state and re-log in. The browser bridge will collect fresh client_id and client_secret values. 
authsome remove <provider>
authsome login <provider>
remove deletes provider state for the current profile, including any stored OAuth client credentials. The provider definition (bundled or custom) is unaffected. The next login triggers the browser form to collect fresh values.

​
Provider not connected at all

If authsome list shows the provider as available (not configured, not connected), there’s no credential to fail on. Run: 
authsome login <provider>
If the provider isn’t in the bundled set, register a custom definition first. See Custom providers.

​
Still failing

  • Run authsome --verbose login <provider> to surface the full daemon round-trip and the exact provider response.
  • Check ~/.authsome/audit.log for the most recent action and outcome.
  • See Diagnose with doctor for installation-level checks.
  • For HTTPS / TLS errors specifically, see Proxy networking.
  • For token-refresh internals, see Token refresh.

​
What’s next

OAuth callbacks

Diagnose callbacks that don’t land.

Token refresh

How automatic refresh works and when it doesn’t.