HTTP daemon API

Every route the local authsome daemon exposes on 127.0.0.1:7998. Health, auth sessions, connections, providers, proxy resolution, dashboard UI.

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_BASE_URL / AUTHSOME_BASE_URL overrides, see The local daemon.

Health and readiness

GET /api/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.

configured_encryption_mode · string

The configured master-key resolution mode, for example auto, local_key, or keyring.

effective_encryption_source · string

The effective master-key source chosen at runtime, for example env, keyring, or local_key.

encryption_backend · string

Human-readable description of the effective master-key source.

GET /api/ready

Readiness probe. Verifies store, vault, identity, providers, and connections for the authenticated caller.

status · string · required

Overall readiness: "ready" when all checks pass, "not_ready" when issues is non-empty.

checks · object · required

Per-component status.

Show checks fields

store · string · required

"ok" if the relational store opens and passes a health probe. Failures: "failed".

vault · string · required

"ok" if the encrypted KV store accepts a read/write roundtrip. Failures: "failed".

integrity · string · required

"ok" if the vault integrity check succeeds. Failures: "failed".

identity · string · required

"ok" if the caller’s identity is registered.

providers · string · required

"ok" if every bundled and custom provider definition parses. Failures: "failed".

connections · string · required

"ok" if connection records load for the active vault. Failures: "failed".

spec_version · string · required

"ok" if the server config schema version matches.

redis · string

Present when Redis is configured. "ok" after a successful ping.

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 "not_ready". Each entry is a human-readable string suitable for surfacing in a monitoring alert.

configured_encryption_mode · string

The configured master-key resolution mode.

effective_encryption_source · string

The effective master-key source chosen at runtime, for example env, keyring, or local_key.

encryption_backend · string

Human-readable description of the effective master-key source.

GET /api/whoami

Returns context for the authenticated caller (same data as authsome whoami --json).

home · string · required

Absolute path to the authsome home directory.

identity · string · required

Registered identity handle.

principal_id · string

Opaque Principal identifier when the identity claim is accepted.

vault_id · string

Opaque Vault identifier for the active credential store.

principal_role · string

admin or user.

did · string

The identity’s did:key URI.

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.

Method	Path	Purpose
POST	/api/auth/sessions	Start a new auth session for a provider.
GET	/api/auth/sessions/{session_id}	Get session status.
POST	/api/auth/sessions/{session_id}/resume	Continue a paused or partial flow.
GET	/auth/callback/oauth	OAuth2 callback target (PKCE / DCR). Browser route, not under /api.
GET	/api/auth/sessions/{session_id}/input	Browser form for API-key or OAuth client credential entry.
GET	/api/auth/sessions/{session_id}/device	Device-code verification page.
POST	/api/auth/sessions/{session_id}/input	Submit 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 daemon’s credential service, which manages decryption, refresh, and vault writes.

Method	Path	Purpose
GET	/api/connections	List every connection across all bundled and custom providers.
GET	/api/connections/{provider}/{connection}	Fetch one connection record. Secrets are redacted unless explicitly requested.
POST	/api/connections/{provider}/{connection}/logout	Remove a single connection record from the local store.
POST	/api/connections/{provider}/revoke	Call the provider’s revocation endpoint (where supported) and clear all connections for the provider.
POST	/api/connections/{provider}/{connection}/default	Set this connection as the provider’s default.

Providers

Method	Path	Purpose
GET	/api/providers	List every bundled and custom provider with auth type, flow, and source.
GET	/api/providers/{provider}	Full provider definition.
POST	/api/providers	Register a custom provider definition.
DELETE	/api/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 authsome run. The proxy never holds decryption keys. It asks the daemon for fresh credentials on each request.

Method	Path	Purpose
GET	/api/proxy/routes	Return the provider-to-host routing table the proxy uses to decide which provider matches an outbound request.
POST	/api/credentials/resolve	Resolve 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

The Next.js dashboard is served as a static export at the daemon root. Browser-only form routes remain for account sessions and provider login starts.

Method	Path	Purpose
GET	/	Static dashboard shell.
POST	/api/session	Return the dashboard URL for a PoP-authenticated local client.
POST	/api/auth/login	Create a browser dashboard session.
POST	/api/auth/register	Register an account and create a browser dashboard session.
POST	/api/logout	Clear the browser dashboard session.
GET	/api/claim/{token}	Render the account claim confirmation page.
POST	/api/claim/{token}/confirm	Attach a local identity to the signed-in account.
POST	/api/auth/providers/{provider_name}/connect	Start a provider login flow from the dashboard.

Auth

Protected /api/* routes require a Proof-of-Possession (PoP) JWT in the Authorization: PoP <jwt> header, signed by the caller’s Ed25519 identity key. The CLI and proxy attach this automatically. See Daemon trust boundary for the trust model.

Calling the API directly

Unauthenticated liveness:

curl -s http://127.0.0.1:7998/api/health

Protected routes require PoP signing (use the CLI or follow src/authsome/cli/client.py). Example paths:

curl -s http://127.0.0.1:7998/api/providers | jq '.[].name'
curl -s http://127.0.0.1:7998/api/connections | jq
curl -s http://127.0.0.1:7998/api/proxy/routes | jq

When AUTHSOME_BASE_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_BASE_URL and AUTHSOME_HOME.