> ## Documentation Index
> Fetch the complete documentation index at: https://agentr-441-feat-always-require-a-named-connection-on-login.mintlify.site/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. **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`.

<Note>
  `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).
</Note>

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).

## 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).

```bash theme={null}
authsome login github --connection work       # first connection: becomes the default
authsome login github --connection personal    # second connection
```

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

```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 resolves the provider's default connection from metadata.

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

The default is a pointer stored in provider metadata. Point it at any existing connection with `connections set-default`:

```bash theme={null}
authsome connections set-default github work
```

Use `--force` on `login` to re-authenticate an existing connection in place:

```bash theme={null}
authsome login github --connection work --force
```

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

```bash theme={null}
authsome connections set-default github work
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>