Skip to main content

Documentation Index

Fetch the complete documentation index at: https://authsome.agentr.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 the entire credential set. Different vault file, different lock. 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 vault, different key.

​
At a glance

ProfileConnection
StorageSeparate SQLite file per profileDifferent key in the same SQLite file
EncryptionSame master key (top-level master.key)Same record encryption inside the vault
IsolationTotal. One profile cannot see another.Within a provider only. Same provider can hold many.
CLI flag(active profile via config.json)--connection <name> on every read/write command
Use whenYou want credential sets that never see each otherYou 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: 
uvx authsome login github --connection personal
uvx authsome login github --connection work
uvx 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 its own SQLite store with its own audit log. 
~/.authsome/
  profiles/
    default/  ← personal
    work/     ← employer
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

Authsome no longer reads an active profile from default_profile in config.json. The daemon scopes protected calls by the registered identity handle in the PoP token, and validates that handle against its server-owned registry.

​
On-disk shape

~/.authsome/
config.json
master.key
profiles/
default/
store.db
lock
work/
store.db
lock
config.json holds the active profile name. master.key is shared across all profiles. Each store.db is independently encrypted under the same master key. The vault key namespace inside each store.db: 
profile:<profile>:<provider>:metadata
profile:<profile>:<provider>:state
profile:<profile>:<provider>:client
profile:<profile>:<provider>:connection:<connection_name>
See Credential storage for the full key model and what each row holds.

​
What’s next

Profiles

Create, switch, and manage profiles.

Multiple connections per provider

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