Skip to main content
Authsome ships as a Python package, but the supported integration surface for agents is not an in-process credential API. Use one of these paths instead:
  1. authsome run -- <command> — recommended. The proxy injects credentials without exposing secrets to the child process.
  2. authsome export <provider> --format env — when the tool cannot route through an HTTP proxy.
  3. Daemon HTTP API — when you are building tooling that talks to the local daemon over PoP-authenticated HTTP.
The CLI plus proxy covers almost every workflow. Drop to export or the HTTP API only when embedding authsome in custom orchestration or non-Python runtimes. See Run agents with the proxy.

​
Install

pip install authsome
# or
uv pip install authsome
Python 3.13 or newer.

​
Quick start (proxy)

authsome onboard
authsome login github
authsome run -- python my_script.py
Your script reads placeholder env vars; the proxy substitutes real credentials on outbound HTTP requests. No authsome import required in the script.

​
Quick start (export)

eval "$(authsome export github --format env)"
python -c 'import os; print(os.environ["GITHUB_ACCESS_TOKEN"][:8] + "...")'
Refresh is handled by the daemon. Re-run export when you need fresh values in a long-lived shell.

​
Quick start (daemon HTTP API)

The CLI and proxy both call the daemon at http://127.0.0.1:7998/api/... with PoP JWT authentication. Every protected request carries Authorization: PoP <jwt> signed by the local Ed25519 identity key. 
curl -s http://127.0.0.1:7998/api/health | jq
curl -s http://127.0.0.1:7998/api/connections | jq
See HTTP daemon API for every route. For programmatic PoP signing, follow src/authsome/cli/client.py in the repository — that client is the reference implementation.

​
Public package exports

The top-level authsome package re-exports models, errors, and the Vault interface for tests and advanced embedding: 
from authsome import (
    Vault,
    AuthType,
    ConnectionRecord,
    ConnectionStatus,
    ExportFormat,
    FlowType,
    ProviderDefinition,
    ProviderType,
    Sensitive,
    AuthsomeError,
    AuthenticationFailedError,
    ConnectionNotFoundError,
    CredentialMissingError,
    IdentityNotFoundError,
    ProviderNotFoundError,
    RefreshFailedError,
    TokenExpiredError,
)
CredentialService (the daemon’s credential lifecycle coordinator) lives in authsome.server and is constructed by the daemon’s dependency injection layer. It is not a supported public embedding API.

​
Vault

A minimal encrypted key-value interface. Credential records are stored under keys like vault:<vault_id>:<provider>:connection:<name>. Direct vault access is rare outside tests: 
vault.get(key)
vault.put(key, value)
vault.delete(key)
vault.list(prefix)
Prefer the CLI or daemon API; they manage encryption, refresh, and Principal/Vault authorization for you.

​
Errors

All exceptions subclass AuthsomeError. Common ones:
ExceptionWhen
ProviderNotFoundErrorUnknown provider name
ConnectionNotFoundErrorRequested connection doesn’t exist
CredentialMissingErrorProvider registered but no completed connection
RefreshFailedErrorProvider rejected the refresh token
TokenExpiredErrorToken expired and refresh wasn’t possible
AuthenticationFailedErrorLogin flow failed or was cancelled
IdentityNotFoundErrorIdentity handle not registered with the daemon
StoreUnavailableErrorVault or store unreachable
Exit codes in CLI reference map one-to-one to these classes.

​
When to use which surface

Use the proxyUse exportUse the HTTP API
Python/Node/any HTTP agentSDKs that ignore proxiesCustom tooling on top of authsome
Secrets must not appear in envShort-lived shell sessionsNon-Python orchestrators
Default for new integrationsTLS-pinned SDKsDashboards and automation

​
What’s next

Architecture

Identity, Vault, Principal, and the daemon.

HTTP daemon API

Every route the daemon exposes.