Python library

Use authsome from Python via the CLI, proxy, export, or daemon HTTP API.

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:

Exception	When
ProviderNotFoundError	Unknown provider name
ConnectionNotFoundError	Requested connection doesn’t exist
CredentialMissingError	Provider registered but no completed connection
RefreshFailedError	Provider rejected the refresh token
TokenExpiredError	Token expired and refresh wasn’t possible
AuthenticationFailedError	Login flow failed or was cancelled
IdentityNotFoundError	Identity handle not registered with the daemon
StoreUnavailableError	Vault or store unreachable

Exit codes in CLI reference map one-to-one to these classes.

When to use which surface

Use the proxy	Use export	Use the HTTP API
Python/Node/any HTTP agent	SDKs that ignore proxies	Custom tooling on top of authsome
Secrets must not appear in env	Short-lived shell sessions	Non-Python orchestrators
Default for new integrations	TLS-pinned SDKs	Dashboards and automation

What’s next

Architecture

Identity, Vault, Principal, and the daemon.

HTTP daemon API

Every route the daemon exposes.