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.

The general pattern for any Python script that calls external APIs. No framework required.

​
Run under the proxy

The script reads env vars normally; authsome injects the real values at the proxy layer. 
uvx authsome login openai
uvx authsome login github
uvx authsome run -- python my_script.py
In the script: 
import os
import httpx

# These look like real values to the script but are placeholders.
# Authsome's proxy substitutes the real secret on outbound requests.
key = os.environ["OPENAI_API_KEY"]
gh = os.environ["GITHUB_ACCESS_TOKEN"]

r = httpx.get("https://api.openai.com/v1/models", headers={"Authorization": f"Bearer {key}"})
print(r.json())

r = httpx.get("https://api.github.com/user", headers={"Authorization": f"Bearer {gh}"})
print(r.json())
No authsome import in the script. The proxy does the work. This is the recommended path for almost every script.

​
Embedding the library

When you’re wiring authsome into a larger Python orchestrator and want per-call connection selection or programmatic access to connection metadata: 
from authsome.server.dependencies import create_auth_service

auth = create_auth_service()

openai_key = auth.get_access_token("openai", connection="default")
github_token = auth.get_access_token("github", connection="work")

import httpx
r = httpx.get(
    "https://api.openai.com/v1/models",
    headers={"Authorization": f"Bearer {openai_key}"},
)
Refresh is silent. Re-call get_access_token if your process outlives a token TTL. See Python library for the full surface.

​
When the proxy isn’t enough

The library is the right tool when:
  • The SDK pins TLS certificates and refuses to trust the mitmproxy CA.
  • You’re using non-HTTP protocols (WebSockets, gRPC over HTTP/2, raw TCP) that the proxy can’t intercept.
  • You need to pick a different connection per call within the same process.
  • You’re embedding authsome inside a larger orchestrator with its own subprocess management.
Otherwise, the proxy is simpler.

​
Multi-account

auth.get_access_token("github", connection="personal")
auth.get_access_token("github", connection="work")
See Multiple connections per provider.

​
What’s next

Python library

Every part of the library surface.

Run agents with the proxy

The proxy injection model.