Generic Python agent

Any Python script that calls third-party APIs. Run it under the proxy; drop to the library only when embedding.

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.

authsome login openai
authsome login github
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.