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 authsome daemon serves a small FastAPI HTTP surface on 127.0.0.1:7998 by default. The CLI, the proxy, and the dashboard UI all call it through these routes. This page documents every prefix so you can build tooling on top of authsome without going through the CLI. For the lifecycle, trust model, and AUTHSOME_DAEMON_URL / AUTHSOME_SERVER_BASE_URL overrides, see The local daemon.

​
Health and readiness

​
GET /health

Liveness probe. Returns when the daemon process is up and responding, regardless of subsystem state.
​
status
string
required
Always "ok" for a 200 response.
​
version
string
required
The installed authsome package version.

​
GET /ready

Readiness probe. Verifies vault, schema version, and provider parsing.
​
status
string
required
Overall readiness: "ok", "degraded", or "unhealthy".
​
checks
object
required
Per-component status.
​
warnings
string[]
Non-fatal observations that do not block readiness. Examples: a custom provider override of a bundled name, a master.key with mode 0644 instead of 0600.
​
issues
string[]
Fatal problems. When non-empty, status is "unhealthy". Each entry is a human-readable string suitable for surfacing in a monitoring alert.

​
GET /whoami

Returns the same payload as uvx authsome whoami.
​
home
string
required
Absolute path to the authsome home directory.
​
encryption
object
required
Encryption mode (local_key or keyring) and backend status.
​
profile
string
required
Registered identity handle.

​
Auth sessions

These routes drive browser bridges and OAuth callbacks. The CLI starts a session, opens a browser at one of the page routes, waits for completion, and finalizes the connection.
MethodPathPurpose
POST/auth/sessionsStart a new auth session for a provider.
GET/auth/sessions/{session_id}Get session status.
POST/auth/sessions/{session_id}/resumeContinue a paused or partial flow.
GET/auth/callback/oauthOAuth2 callback target (PKCE / DCR).
GET/auth/sessions/{session_id}/inputBrowser form for API-key or OAuth client credential entry.
GET/auth/sessions/{session_id}/deviceDevice-code verification page.
POST/auth/sessions/{session_id}/inputSubmit values from the input form.
Session state is held in daemon memory. A daemon restart loses any session that is mid-flight.

​
Connections

CRUD for connection records. Behind the scenes, every route goes through the AuthLayer, which manages decryption, refresh, and vault writes.
MethodPathPurpose
GET/connectionsList every connection across all bundled and custom providers.
GET/connections/{provider}/{connection}Fetch one connection record. Secrets are redacted unless explicitly requested.
POST/connections/{provider}/{connection}/logoutRemove a single connection record from the local store.
POST/connections/{provider}/revokeCall the provider’s revocation endpoint (where supported) and clear all connections for the provider.
POST/connections/{provider}/{connection}/defaultSet this connection as the provider’s default.
POST/credentials/exportReturn KEY=value lines or JSON for a provider’s connection, mirroring uvx authsome export.

​
Providers

MethodPathPurpose
GET/providersList every bundled and custom provider with auth type, flow, and source.
GET/providers/{provider}Full provider definition.
POST/providersRegister a custom provider definition (the body is the JSON in Provider schema).
DELETE/providers/{provider}Remove a custom provider or reset a bundled one to its shipped form.

​
Proxy resolution

These routes back the local HTTP proxy started by uvx authsome run. The proxy never holds decryption keys itself; it asks the daemon for fresh credentials per request.
MethodPathPurpose
GET/proxy/routesReturn the provider-to-host routing table the proxy uses to decide which provider matches an outbound request.
POST/credentials/resolveResolve a credential for a host. Returns the value the proxy injects into the Authorization header (or whatever header the provider’s api_key.header_name declares).

​
Dashboard UI

These routes serve HTML. The dashboard is mounted under the /ui prefix.
MethodPathPurpose
GET/ui/Dashboard overview.
GET/ui/connectionsAll connections, by provider.
GET/ui/apps/{provider_name}Detail pane for one provider.
POST/ui/apps/{provider_name}/{connection_name}/disconnectLog out from the dashboard UI.
POST/ui/apps/{provider_name}/connectStart a flow from the dashboard UI.

​
Auth

There is no bearer token between the CLI, the proxy, and the daemon in v1. Loopback binding (127.0.0.1) is the only access control. See Daemon trust boundary for the trust model and known limitations.

​
Calling the API directly

curl -s http://127.0.0.1:7998/health
curl -s http://127.0.0.1:7998/providers | jq '.[].name'
curl -s http://127.0.0.1:7998/connections | jq
curl -s http://127.0.0.1:7998/proxy/routes | jq
When AUTHSOME_DAEMON_URL is set to a hosted daemon URL, replace http://127.0.0.1:7998 with that URL.

​
Building on top

The schemas backing every route live in src/authsome/server/schemas.py in the source tree. The OpenAPI spec is served at /docs (Swagger UI) and /openapi.json by FastAPI’s defaults. 
curl -s http://127.0.0.1:7998/openapi.json | jq '.paths | keys'

​
What’s next

The local daemon

Lifecycle, routes, and v1 limitations.

Daemon trust boundary

What loopback-only access control protects against.

Daemon issues

Port conflicts, lost sessions, and restart behavior.

Environment variables

AUTHSOME_DAEMON_URL and AUTHSOME_SERVER_BASE_URL.