OAuth callback errors

redirect_uri_mismatch

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:

Open your OAuth app settings

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

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.

Save and retry login

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 authsome inspect <provider> for supports_dcr: true.

Port 7998 already in use

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.

Browser does not open

The terminal prints the authorization URL but no browser launches.

Cause	Fix
You’re SSHed into a remote machine	Use `--flow device_code` instead. See Headless setup.
`webbrowser` Python module can’t find a default browser	Set `BROWSER` env var: `export BROWSER=$(which firefox)`.
Headless Linux without `DISPLAY`	Same 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.

Browser opens but never returns to authsome

The browser shows the provider’s authorization page, you click Authorize, and nothing. The terminal is still waiting.

Cause	Fix
The browser landed on `http://127.0.0.1:7998/auth/callback/oauth` but authsome timed out	Re-run `authsome login --force`.
A corporate proxy is intercepting `127.0.0.1` traffic	Add `127.0.0.1` and `localhost` to your `NO_PROXY` env var.
You authorized in a different browser profile that can’t reach localhost	Use the same browser profile as your authsome shell.

state mismatch error

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.

client_id or client_secret rejected

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.

authsome revoke <provider>     # clear stored client + tokens
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.

Scopes not granted

The login completes but the agent gets 403 Insufficient scope on real API calls.

authsome get <provider> --field scopes

If the granted scopes don’t include what your agent needs:

authsome login <provider> --scopes "<scope1>,<scope2>" --force

The provider re-prompts for consent on the additional scopes.

Token refresh

What to do when a refresh fails.

Headless device code

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

Guides

Troubleshooting

OAuth callback errors

What’s next

Token refresh

Headless device code

​What’s next

Token refresh

Headless device code

What’s next