Summary
Today the first connection for a provider is stored under the literal name default. A user-chosen name is only required when adding a second connection (via NamedConnectionDialog in the UI or --connection on the CLI). The default connection should be a property (ProviderMetadataRecord.default_connection) pointing at a named connection — not a connection whose name is "default".
Current behavior
- UI first-time connect posts
connection=default (ui/src/components/dashboard/provider-views.tsx).
requiresNamedLogin is true only when a "default" connection already exists (ui/src/lib/authsome-api.ts).
- Server connect handler falls back to
"default" when no name is supplied (src/authsome/server/routes/ui.py).
- CLI
login defaults --connection to "default" (src/authsome/cli/commands/core.py).
ProviderMetadataRecord.default_connection defaults to "default" (src/authsome/auth/models/connection.py).
- Docs describe the default connection as literally named
default (docs/site/guides/multiple-connections.mdx).
Proposed behavior
Always prompt for (or require) a user-chosen connection name when connecting a provider — including the first connection. That name becomes the stored connection_name. The provider's default is then set to that name via default_connection metadata, not by using "default" as the key.
Examples:
- User names first GitHub connection
work → stored at vault:…:github:connection:work, default_connection = "work".
- User adds a second connection
personal → stored separately; default_connection unchanged unless explicitly switched.
- Commands/API calls that omit
--connection resolve via default_connection metadata (existing resolve_connection_name behavior), not by assuming a connection named "default" exists.
Scope
UI
- Always show the connection-name dialog (or inline name field) before starting OAuth/API-key flow, even when
connectionCount === 0.
- Remove hidden
connection=default form posts.
- Update provider detail "Connect" flow similarly (
provider-detail-view.tsx).
CLI
- Require
--connection <name> on authsome login, or prompt interactively when omitted (TBD — pick one and document).
- Stop defaulting
--connection to "default".
Server / storage
connect routes should reject or prompt when connection_name is missing or equals the reserved name default (if we deprecate that literal).
- On first connection save, set
metadata.default_connection to the chosen name.
resolve_connection_name / resolve_effective_connection should not assume a "default" connection record exists; fall back to default_connection metadata only.
- Consider migration for existing vaults that already have a
default connection (rename? alias? keep reading "default" as legacy?).
Docs
- Update
docs/site/guides/multiple-connections.mdx and any CLI reference to reflect named-first connections.
Acceptance criteria
Open questions
- Should
"default" remain a reserved/legacy alias for backward compatibility, or be fully removed?
- Interactive CLI prompt vs hard requirement for
--connection?
- Auto-suggest a name (e.g. provider name, account email) vs blank required field?
References
ui/src/components/dashboard/provider-views.tsx (NamedConnectionDialog, requiresNamedLogin)
src/authsome/server/routes/ui.py (connect_provider)
src/authsome/server/credential_service.py (resolve_connection_name, set_default_connection)
src/authsome/auth/models/connection.py (ProviderMetadataRecord)
Summary
Today the first connection for a provider is stored under the literal name
default. A user-chosen name is only required when adding a second connection (viaNamedConnectionDialogin the UI or--connectionon the CLI). The default connection should be a property (ProviderMetadataRecord.default_connection) pointing at a named connection — not a connection whose name is"default".Current behavior
connection=default(ui/src/components/dashboard/provider-views.tsx).requiresNamedLoginistrueonly when a"default"connection already exists (ui/src/lib/authsome-api.ts)."default"when no name is supplied (src/authsome/server/routes/ui.py).logindefaults--connectionto"default"(src/authsome/cli/commands/core.py).ProviderMetadataRecord.default_connectiondefaults to"default"(src/authsome/auth/models/connection.py).default(docs/site/guides/multiple-connections.mdx).Proposed behavior
Always prompt for (or require) a user-chosen connection name when connecting a provider — including the first connection. That name becomes the stored
connection_name. The provider's default is then set to that name viadefault_connectionmetadata, not by using"default"as the key.Examples:
work→ stored atvault:…:github:connection:work,default_connection = "work".personal→ stored separately;default_connectionunchanged unless explicitly switched.--connectionresolve viadefault_connectionmetadata (existingresolve_connection_namebehavior), not by assuming a connection named"default"exists.Scope
UI
connectionCount === 0.connection=defaultform posts.provider-detail-view.tsx).CLI
--connection <name>onauthsome login, or prompt interactively when omitted (TBD — pick one and document).--connectionto"default".Server / storage
connectroutes should reject or prompt whenconnection_nameis missing or equals the reserved namedefault(if we deprecate that literal).metadata.default_connectionto the chosen name.resolve_connection_name/resolve_effective_connectionshould not assume a"default"connection record exists; fall back todefault_connectionmetadata only.defaultconnection (rename? alias? keep reading"default"as legacy?).Docs
docs/site/guides/multiple-connections.mdxand any CLI reference to reflect named-first connections.Acceptance criteria
"default".default_connectionmetadata is set to the first connection's name automatically.--connectionon read/export/get commands still resolves the provider default via metadata."default"connections have a documented migration or backward-compat path.Open questions
"default"remain a reserved/legacy alias for backward compatibility, or be fully removed?--connection?References
ui/src/components/dashboard/provider-views.tsx(NamedConnectionDialog,requiresNamedLogin)src/authsome/server/routes/ui.py(connect_provider)src/authsome/server/credential_service.py(resolve_connection_name,set_default_connection)src/authsome/auth/models/connection.py(ProviderMetadataRecord)