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.

GitHub is a bundled OAuth2 provider in authsome. The default flow is browser-based PKCE; the device code flow is supported for headless setups. Tokens are stored in the local encrypted vault and refreshed transparently before expiry.

​
At a glance

Provider namegithub
Display nameGitHub
Auth typeOAuth2
Default flowpkce
Device code supportedYes
DCR supportedNo
Default scopesrepo, read:user
Proxy hostapi.github.com
Env var (access_token)GITHUB_ACCESS_TOKEN
Env var (refresh_token)GITHUB_REFRESH_TOKEN
Provider docsdocs.github.com/…

​
Prerequisites

GitHub does not support Dynamic Client Registration, so you need to register an OAuth app once. This is a one-time setup per app, not per developer.
1

Create a new OAuth app

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

Set the callback URL

Set Authorization callback URL to:
http://127.0.0.1:7998/auth/callback/oauth
This is the only callback URL authsome’s PKCE flow listens on.
3

Save the client ID and secret

Copy the Client ID and Client Secret. Authsome will prompt for them on first login through a secure local browser form. You will not paste them into a terminal.

​
Log in

uvx authsome login github
What happens:
1

Client credential collection (first time only)

Authsome opens a local form at http://127.0.0.1:7998. Paste the 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 https://github.com/login/oauth/authorize. Approve the requested scopes.
3

Token exchange

GitHub redirects to http://127.0.0.1:7998/auth/callback/oauth with an authorization code. Authsome exchanges it for an access token and stores the encrypted record.
4

Confirmation

The terminal prints Successfully logged in to github (default).
Verify: 
uvx authsome get github --field status
# → connected

​
Headless setup (SSH, CI)

For machines without a local browser, use the device code flow: 
uvx authsome login github --flow device_code
Authsome prints a verification URL and a short user code. Open the URL on any device, enter the code, approve the app, and authsome’s poll completes. Device code uses GitHub’s public OAuth client, so you can skip the OAuth app registration entirely for personal use. See Headless setup for the full flow.

​
Custom scopes

The bundled definition requests repo and read:user. Override at login time: 
uvx authsome login github --scopes "repo,read:user,workflow,gist"
The granted scopes are stored on the connection and visible in uvx authsome get github. For the full list of GitHub OAuth scopes, see GitHub’s scopes documentation.

​
GitHub Enterprise

For self-hosted GitHub Enterprise, pass the base URL of your instance: 
uvx authsome login github --base-url https://github.acme.com
The base URL is saved on the connection and reused for every token refresh. The bundled definition uses {base_url} placeholders for the authorization, token, and device code endpoints, so substitution is automatic.

​
Multiple accounts

Personal and work GitHub on the same machine: 
uvx authsome login github --connection personal
uvx authsome login github --connection work
Read either side: 
uvx authsome get github --connection work
uvx authsome export github --connection personal --format env
Pass --connection <name> on login and on every read command to keep two or more accounts on the same provider side by side. See Multiple connections per provider for the full pattern.

​
Use the token

Run the agent under the proxy. The library tab is for embedding authsome inside a larger Python orchestrator. 
uvx authsome run -- python my_agent.py
Under the proxy, authsome sets GITHUB_ACCESS_TOKEN=authsome-proxy-managed in the child’s environment and injects the real token into outbound requests to api.github.com. The child process never sees the actual value. Refresh tokens are never exported.

​
Override the bundled definition

To change scopes or point at GitHub Enterprise by default, drop a custom JSON at ~/.authsome/providers/github.json. The user-registered file always wins over the bundled one. 
uvx authsome inspect github > ~/.authsome/providers/github.json
# edit scopes, base_url, or anything else
uvx authsome list   # source now shows "custom" for github
The schema is documented in Provider schema.

​
Troubleshooting

SymptomLikely causeFix
redirect_uri_mismatch at github.comOAuth app callback URL is wrongSet it to http://127.0.0.1:7998/auth/callback/oauth exactly.
Browser opens but the form is blankDaemon not running or port helduvx authsome doctor and check that port 7998 is free.
Bad credentials after a successful loginToken revoked at GitHubuvx authsome login github --force to re-authenticate.
Refresh fails after long idleGitHub access tokens do not expire by default; refresh is rarely neededIf the connection shows expired, run uvx authsome login github --force.
For deeper diagnostics, see OAuth callbacks and Token refresh.

​
What’s next

Run agents with the proxy

Inject the access token into outbound requests without exposing it.

Multiple connections per provider

Keep two or more accounts on the same provider side by side.

Provider schema

Every field in a provider definition.

OAuth providers

All bundled OAuth providers.