Skip to main content

Documentation Index

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

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

The PKCE flow uses the local daemon on 127.0.0.1:7998 to receive the OAuth callback at /auth/callback/oauth. Most login failures fall into one of the categories below.
The provider’s authorization page returns:
The redirect_uri MUST match the registered callback URL for this application.
Authsome listens on a single redirect URI:
http://127.0.0.1:7998/auth/callback/oauth
Fix it at the provider:
1

Open your OAuth app settings

For GitHub: github.com/settings/developers. For other providers, find the equivalent OAuth app management page.
2

Edit the callback URL

Set Authorization callback URL (or the equivalent field) to http://127.0.0.1:7998/auth/callback/oauth. The full path matters, it must be /auth/callback/oauth.
3

Save and retry login

uvx authsome login <provider> --force
For services that support Dynamic Client Registration, the dcr_pkce flow registers a fresh OAuth client with the right redirect URI automatically. Check uvx authsome inspect <provider> for supports_dcr: true.
Error: address already in use: 127.0.0.1:7998
Another process is bound to the daemon port. The CLI reuses an existing authsome daemon if one is already running; you only see this error when something else holds 7998. Find and stop it:
# macOS / Linux
lsof -nP -iTCP:7998 -sTCP:LISTEN
kill <PID>
If a stale authsome daemon won’t release the port, pkill -f authsome then re-run any CLI command. See Daemon issues.
The terminal prints the authorization URL but no browser launches.
CauseFix
You’re SSHed into a remote machineUse --flow device_code instead. See Headless setup.
webbrowser Python module can’t find a default browserSet BROWSER env var: export BROWSER=$(which firefox).
Headless Linux without DISPLAYSame as SSH, use the device code flow.
You can also copy the URL printed in the terminal and open it manually on any device. As long as the redirect lands on http://127.0.0.1:7998/auth/callback/oauth on the same machine where authsome is waiting, the flow completes.
The browser shows the provider’s authorization page, you click Authorize, and nothing. The terminal is still waiting.
CauseFix
The browser landed on http://127.0.0.1:7998/auth/callback/oauth but authsome timed outRe-run uvx authsome login --force.
A corporate proxy is intercepting 127.0.0.1 trafficAdd 127.0.0.1 and localhost to your NO_PROXY env var.
You authorized in a different browser profile that can’t reach localhostUse the same browser profile as your authsome shell.
Error: OAuth state parameter does not match
Authsome generates a random state parameter and rejects callbacks that don’t echo it back. Causes:
  • A stale tab from a previous login is hitting the callback. Close it and retry.
  • A man-in-the-middle is replaying old callback URLs. Investigate before retrying.
The provider’s token endpoint returns invalid_client.
Error: token exchange failed: invalid_client
The stored client credentials don’t match what the provider expects.
uvx authsome revoke <provider>     # clear stored client + tokens
uvx authsome login <provider>      # re-enter client_id and client_secret via browser bridge
If you’ve recently rotated the OAuth app’s client secret, this is the expected flow.
The login completes but the agent gets 403 Insufficient scope on real API calls.
uvx authsome get <provider> --field scopes
If the granted scopes don’t include what your agent needs:
uvx authsome login <provider> --scopes "<scope1>,<scope2>" --force
The provider re-prompts for consent on the additional scopes.

​
What’s next

Token refresh

What to do when a refresh fails.

Headless device code

The right flow when you can’t run a browser locally.