authsome 0.1.5

A portable local authentication library for AI agents and developer tools

authsome

OAuth2 and API key management for agents. Local. Headless. Portable.

Authenticate once. Get valid headers anywhere. No server, no account, no cloud.

---

The Problem

Agents and developer tools need to call APIs. Authentication keeps getting in the way:

• OAuth2 flows are stateful — browsers, callbacks, token exchange
• Tokens expire — refresh logic gets reinvented in every project
• API keys get hardcoded or lost in shell profiles
• There's no standard answer to: "give me a valid GitHub token right now"

Authsome is a local authentication layer that handles login, logout, and token refresh for your agents and scripts. You ask for headers. You get headers. It's the agent's job to call APIs — it's authsome's job to keep the credentials fresh.

---

What It Does

• Login flows — PKCE, Device Code, Dynamic Client Registration, API key prompt
• Automatic token refresh — tokens are refreshed before expiry, transparently
• One call for valid headers — always returns a usable Authorization header
• Subprocess injection — run any command with credentials in its environment
• Headless-friendly — Device Code flow works in CI, SSH sessions, and remote agents
• 35 bundled providers — GitHub, Google, OpenAI, Linear, Slack, and more, zero config
• Portable — follows your ~/.authsome directory; works on any machine you're on

---

Quick Start

pip install authsome
authsome init
authsome login github      # opens browser, completes OAuth2 PKCE flow
authsome login openai      # prompts for API key
authsome list              # all authenticated services and token status

from authsome import AuthClient

client = AuthClient()

# Always returns a valid, refreshed Authorization header
headers = client.get_auth_headers("github")
# → {"Authorization": "Bearer ghu_..."}

headers = client.get_auth_headers("openai")
# → {"Authorization": "Bearer sk-..."}

# Inject credentials into any subprocess — no env files needed
client.run(["python", "script.py"], providers=["github", "openai"])

---

Why Authsome

Your agent should call APIs, not manage auth state. Authsome is the authentication layer between your agent and the services it uses — local, offline-capable, and zero-dependency on external infrastructure.

	Authsome	Manual .env	Roll your own
OAuth2 flows (PKCE, Device, DCR)	✅	❌	build it
Automatic token refresh	✅	❌	build it
35 providers, zero config	✅	❌	build it
Headless / CI / SSH	✅	✅	varies
Multi-account per provider	✅	❌	build it
No server, no account	✅	✅	✅

---

CLI Reference

# Setup
authsome init                          # initialize ~/.authsome
authsome doctor                        # verify installation health

# Authentication
authsome login github                  # OAuth2 browser flow (PKCE)
authsome login github --flow device    # headless Device Code flow
authsome login openai                  # API key prompt
authsome logout github                 # revoke token remotely + remove locally
authsome remove github                 # remove local state only

# Inspect
authsome list                          # all connections + token status
authsome get github                    # connection metadata (secrets redacted)
authsome get github --show-secret      # reveal token
authsome get github --field status     # extract one field

# Export & run
authsome export github --format shell  # → export GITHUB_TOKEN=...
authsome run --provider openai -- python script.py

All commands support --json for machine-readable output and --profile to switch between credential sets (e.g., personal vs. work).

---

Bundled Providers

35 providers, ready to use with zero configuration:

Developer & Productivity github · google · linear · okta · zapier · calendly · savvycal · typeform · buffer

AI & Data openai · clearbit · ahrefs · semrush · g2 · keywords-everywhere

Marketing & Email mailchimp · klaviyo · brevo · sendgrid · postmark · resend · beehiiv · instantly · lemlist

Sales & CRM apollo · hunter · intercom · mention-me · rewardful · tolt

Media & Analytics wistia · livestorm · optimizely · x · dub

Add your own by dropping a JSON file in ~/.authsome/providers/<name>.json.

---

Technical Deep Dive

Architecture

┌─────────────────┐     ┌──────────────┐     ┌────────────────────┐
│   Agent / Tool  │────▶│  AuthClient  │────▶│  Provider Registry  │
│                 │     │              │     │  (bundled + local)  │
└─────────────────┘     └──────┬───────┘     └────────────────────┘
                               │
                        ┌──────┴───────┐
                        │  Auth Flows  │
                        ├──────────────┤
                        │ • PKCE       │  ← browser OAuth2
                        │ • Device Code│  ← headless / CI
                        │ • DCR + PKCE │  ← dynamic client reg
                        │ • API Key    │  ← prompt or env import
                        └──────┬───────┘
                               │
                        ┌──────┴───────┐
                        │   Storage    │
                        ├──────────────┤
                        │ SQLite KV    │  ← per-profile credential store
                        │ AES-256-GCM  │  ← encrypted at rest
                        └──────────────┘

AuthClient is the single entry point. It resolves the right flow per provider, manages token refresh transparently, and delegates persistence to a per-profile SQLite store. Profiles let you isolate credential sets (e.g., personal, work, a specific agent).

Auth Flows

Flow	When to Use
pkce	Browser-capable environments with a pre-registered OAuth client
device_code	Headless servers, CI, SSH sessions — no browser required
dcr_pkce	Services supporting Dynamic Client Registration — no pre-registration needed
api_key_prompt	Interactive terminal, prompts securely via getpass
api_key_env	Import a key already present in an environment variable

Custom Providers

Via JSON (~/.authsome/providers/my-service.json):

{
  "name": "my-service",
  "display_name": "My Service",
  "auth_type": "api_key",
  "flow": "api_key_prompt",
  "api_key": {
    "header_name": "X-API-Key",
    "header_prefix": "",
    "env_var": "MY_SERVICE_KEY"
  }
}

Via Python:

from authsome import ProviderDefinition, AuthType, FlowType
from authsome.models.provider import ApiKeyConfig

client.register_provider(ProviderDefinition(
    name="my-service",
    display_name="My Service",
    auth_type=AuthType.API_KEY,
    flow=FlowType.API_KEY_PROMPT,
    api_key=ApiKeyConfig(header_name="X-API-Key", header_prefix="", env_var="MY_SERVICE_KEY"),
))

Multiple Connections

Same provider, multiple accounts:

client.login("openai", connection_name="personal")
client.login("openai", connection_name="work")

headers = client.get_auth_headers("openai", connection="work")

Storage Layout

~/.authsome/
  config.json          # global settings (encryption mode, active profile)
  master.key           # encryption key (chmod 0600)
  providers/           # user-defined provider definitions
  config.json          # global settings (encryption mode, active profile)
  master.key           # encryption key (chmod 0600)
  providers/           # user-defined provider definitions
  profiles/
    default/
      store.db         # credential store (SQLite, values AES-256-GCM encrypted)
      store.db         # credential store (SQLite, values AES-256-GCM encrypted)
      lock             # advisory write lock

Environment Variables

Variable	Purpose
AUTHSOME_HOME	Override the default ~/.authsome directory

---

---

License

MIT — see LICENSE.