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.

OAuth2 providers. GitHub, Google, Linear, Slack, Notion, and many of the bundled providers, use a browser-based flow by default. You authenticate once, and authsome takes over token refresh from there.

​
When to use this flow

Use the PKCE browser flow when:
  • Your machine has a graphical browser available.
  • You can register an OAuth app with the provider (or the provider supports Dynamic Client Registration, see the note below).
If you are on a remote SSH session, in CI, or on a server without a browser, use the Device Code flow instead.

​
Register an OAuth app

For services that don’t support Dynamic Client Registration, you need to register an OAuth app with the provider once. The redirect URI must be: 
http://127.0.0.1:7998/auth/callback/oauth
This is the only redirect URI authsome listens on for PKCE flows. GitHub example:
1

Create a new OAuth app

Visit github.com/settings/developers and click New OAuth App.
2

Set the redirect URI

Set Authorization callback URL to http://127.0.0.1:7998/auth/callback/oauth.
3

Save the client ID and secret

Keep the Client ID and Client Secret at hand. Authsome will prompt for them on first login through a secure local browser form. You will not paste them into a terminal.
For services that support , for example, some MCP servers and modern OAuth providers, authsome’s dcr_pkce flow registers an OAuth client automatically. You skip the app-registration step entirely.

​
Run the login

uvx authsome login github
This is what happens:
1

Client credential collection (first time only)

Authsome opens a local form at http://127.0.0.1:7998. Paste your client_id and client_secret. They are encrypted and stored under your profile, then reused on every subsequent login.
2

Authorization redirect

A second browser window opens to the provider’s authorization page. Approve the requested scopes.
3

Token exchange

The provider redirects back to http://127.0.0.1:7998/auth/callback/oauth with an authorization code. Authsome exchanges it for an access token (and a refresh token, if the provider supports them) and stores the encrypted record.
4

Confirmation

The terminal prints Successfully logged in to github (default).
Sensitive values. client_secret, access tokens, refresh tokens, are never accepted as command-line arguments. They never appear in shell history or process listings. Authsome collects them through the secure browser bridge or, on headless machines, through masked terminal input.

​
Override the flow

The default flow lives in the provider definition. Override it on the command line: 
uvx authsome login github --flow device_code
uvx authsome login github --flow pkce
Valid values: pkce, device_code, dcr_pkce, api_key.

​
Custom scopes

Request specific scopes instead of the provider’s default set: 
uvx authsome login github --scopes "repo,read:user,workflow"
The granted scopes are stored on the connection record and visible in uvx authsome get github.

​
Multi-tenant / self-hosted (Enterprise)

Providers like GitHub Enterprise, Okta, and GitLab self-managed run on per-deployment URLs. Pass --base-url: 
uvx authsome login github --base-url https://github.acme.com
The base URL is saved on the connection and reused for every refresh.

​
Multiple connections per provider

The default connection name is default. To log in to a second account on the same provider, pass --connection <name> to login and to every read command. See Multiple connections per provider for the full pattern.

​
Verify the login

uvx authsome list
uvx authsome get github                  # metadata, secrets redacted
uvx authsome get github --field status   # → connected

​
Re-login

If a provider is already connected, uvx authsome login <provider> exits with an error. To overwrite an existing connection: 
uvx authsome login github --force
This skips the “already connected” guard and runs the flow again, replacing the stored credentials. Use uvx authsome revoke github first if you want to invalidate the old token at the provider as well.

​
What’s next

Run agents with the proxy

Inject the access token into outbound requests without exposing it.

Headless device code

Authenticate over SSH or in CI when no local browser is available.