Multiple connections per provider

Keep two or more accounts on the same provider side by side. Personal vs work GitHub, team vs personal OpenAI, and similar.

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 multiple Vaults or Principals instead. The distinction is covered in Principal, Vault, and Identity.

Create a second connection

Pass --connection <name> to login. The name is arbitrary; pick what reads well.

authsome login github                        # default connection
authsome login github --connection work
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:

authsome get github --connection work
authsome get github --connection personal --field status
authsome export github --connection work --format env

Without --connection, the command uses the default.

List connections

authsome list
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:

authsome login github --connection work --force

The --force flag overwrites the existing default slot. Programmatic default switching is on the roadmap.

In the proxy

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:

authsome login github --connection work --force
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

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:

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 Vaults/Principals

You want	Use
Two accounts on the same provider, both reachable	Connections (--connection)
Credential sets that never see each other	Separate Vaults / Principals
Per-agent scoping	Separate Identity / Principal per agent

The full model is in Principal, Vault, and Identity.

What’s next

Principal, Vault, and Identity

The architectural namespaces.

CLI reference

Every command and flag.