Skip to main content
A connection is a named credential record within one provider. Every connection has a name that you choose — including the first one. You can have as many connections as you want, each scoped by name. The provider’s default connection is a pointer to one of your named connections, not a connection literally called default.
default is a reserved name. You cannot create a connection called default; it survives only as a read-time alias for the provider’s default connection (and for vaults created before named-first connections existed).
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.

​
Name your connections

Pass --connection <name> to login. The name is arbitrary; pick what reads well. If you omit --connection, authsome login prompts you for a name (and fails with a usage error in non-interactive contexts such as --quiet or a non-TTY, so scripts must pass it explicitly).
The first connection you create automatically becomes the provider’s default. Subsequent connections leave the default unchanged unless you switch it. 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:
Without --connection, the command resolves the provider’s default connection from metadata.

​
List connections

inspect includes per-connection status, expiry, and scopes.

​
Switch the default

The default is a pointer stored in provider metadata. Point it at any existing connection with connections set-default:
Use --force on login to re-authenticate an existing connection in place:

​
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, point the default at it first:
Or export credentials for a specific connection:

​
Remove a connection

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

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.