Profiles vs connections

When to use a profile and when to use a connection. The two namespaces, why they’re different, and the rule of thumb.

Authsome has two layers of credential namespacing. People confuse them, then end up with credentials in the wrong place. This page makes the distinction explicit.

The two namespaces

profile:<profile_name>:<provider_name>:connection:<connection_name>

• Profile scopes an entire credential set. A profile is an identity handle; credentials are stored under that handle’s key prefix inside the shared KV store. Audit events from all profiles are written to the same ~/.authsome/audit.log and tagged with the profile name.
• Connection scopes a credential record within one provider. Same profile prefix, different sub-key.

At a glance

	Profile	Connection
Storage	Different key prefix in the shared KV store at ~/.authsome/server/kv_store/	Different sub-key under the same profile prefix
Encryption	Same master key (~/.authsome/server/master.key)	Same record encryption inside the vault
Isolation	Total. Records under one profile prefix are unreachable when a different identity handle is active.	Within a provider only. Same provider can hold many.
CLI flag	Identity handle, set by authsome init and stored in the client config	--connection <name> on every read/write command
Use when	You want credential sets that never see each other	You want multiple accounts on the same provider, both reachable

The rule of thumb

If credentials should never see each other, use profiles. If both should be reachable in the same context, use connections within one profile.

Examples

Two GitHub accounts. You want to push to a personal repo and a work repo from the same shell. Use one profile, two connections:

authsome login github --connection personal
authsome login github --connection work
authsome get github --connection work --field access_token --show-secret

Personal vs employer’s tooling. You don’t want personal Slack credentials anywhere near work tooling. Use separate profiles. The work profile is a separate identity handle whose records live under a different key prefix in the same KV store. Switching the active identity is enough to switch credential sets.

Per-agent scoping. You want each agent to only see the credentials it needs. Use a profile per agent: agent-cold-email, agent-pr-bot. The agent’s process runs against that profile only.

Testing a different OAuth client. You want to verify a new client_id without overwriting the canonical one. Spin up a throwaway profile, do the test, delete the profile.

Which one is active

A profile is an identity handle. The daemon scopes every protected request by the handle carried in the request’s PoP token and validates that handle against its server-owned registry. The CLI tracks the active handle in the client config; authsome init creates and registers a handle on first run.

On-disk shape

There is one KV store on disk, shared across every profile, with profile-prefixed keys inside:

~/.authsome/

server/

master.key

kv_store/

master.key is shared across all profiles. Records for every profile live inside server/kv_store/, encrypted under the same master key, separated by key prefix:

profile:default:<provider>:connection:<name>
profile:work:<provider>:connection:<name>
server:<provider>:client                    # daemon-owned, shared across profiles

For the full directory model (identities, audit log, daemon files), see Filesystem layout. For the full vault key model and what each row holds, see Credential storage.

What’s next

Profiles

Create, switch, and manage profiles.

Multiple connections per provider

The connection-flag pattern for two accounts on one provider.