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.

A connection is a named credential record within one provider. The default connection is called default. You can have as many additional connections as you want, each scoped by name. This is the right pattern when you want two accounts on the same provider both reachable from the same context. If you want credential sets that never see each other, use profiles instead. The distinction is covered in Profiles vs connections.

​
Create a second connection

Pass --connection <name> to login. The name is arbitrary; pick what reads well. 
uvx authsome login github                        # default connection
uvx authsome login github --connection work
uvx authsome login github --connection personal
For an OAuth2 provider, each login runs its own browser flow. The connections share the OAuth client_id/client_secret you configured for the provider, but each receives an independent access token bound to its own scopes. For an API-key provider, each login opens a fresh local form so you paste a different key per connection.

​
Read from a specific connection

Every read command accepts --connection: 
uvx authsome get github --connection work
uvx authsome get github --connection personal --field status
uvx authsome export github --connection work --format env
Without --connection, the command uses the default.

​
List connections

uvx authsome list
uvx authsome inspect github       # shows every connection on the provider
inspect includes per-connection status, expiry, and scopes.

​
Switch the default

There is no set-default command in v1. To change which connection authsome treats as default, log in to it with --force: 
uvx authsome login github --connection work --force
The --force flag overwrites the existing default slot. Programmatic default switching is on the roadmap.

​
In the proxy

uvx authsome run injects credentials from each provider’s default connection. Per-request connection selection is future work. To run an agent against a non-default connection, set the active default first: 
uvx authsome login github --connection work --force
uvx authsome run -- python my_agent.py
Or use the library, which accepts connection= directly: 
from authsome.server.dependencies import create_auth_service

auth = create_auth_service()
token = auth.get_access_token("github", connection="work")

​
Remove a connection

uvx authsome logout github --connection work
This removes the local credential record for that connection only. The other connections on the provider stay intact. The provider is not contacted. To call the provider’s revocation endpoint (where supported) and clear local state: 
uvx authsome revoke github                       # all connections + client secrets
revoke does not yet target a single connection; it clears the provider entirely. To revoke only one connection at the provider, use the provider’s own UI and then logout locally.

​
When to use connections vs profiles

You wantUse
Two accounts on the same provider, both reachableConnections (--connection)
Credential sets that never see each otherProfiles (separate vault files)
Per-agent scopingProfile per agent
Temporary OAuth client for testingThrowaway profile
The full model is in Profiles vs connections.

​
What’s next

Profiles vs connections

The two namespaces, side by side.

CLI reference

Every command and flag.