> ## Documentation Index
> Fetch the complete documentation index at: https://authsome.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/concepts/principal-vault-identity).

## Create a second connection

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

```bash theme={null}
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`:

```bash theme={null}
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

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
authsome login github --connection work --force
authsome run -- python my_agent.py
```

Or export credentials for a specific connection:

```bash theme={null}
eval "$(authsome export github --connection work --format env)"
```

## Remove a connection

```bash theme={null}
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:

```bash theme={null}
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](/concepts/principal-vault-identity).

## What's next

<Columns cols={2}>
  <Card title="Principal, Vault, and Identity" icon="users" href="/concepts/principal-vault-identity">
    The architectural namespaces.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/reference/cli">
    Every command and flag.
  </Card>
</Columns>