> ## Documentation Index
> Fetch the complete documentation index at: https://authsome.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/concepts/the-daemon).

## Health and readiness

### `GET /api/health`

Liveness probe. Returns when the daemon process is up and responding, regardless of subsystem state.

<ResponseField name="status" type="string" required>
  Always `"ok"` for a 200 response.
</ResponseField>

<ResponseField name="version" type="string" required>
  The installed `authsome` package version.
</ResponseField>

<ResponseField name="configured_encryption_mode" type="string">
  The configured master-key resolution mode, for example `auto`, `local_key`, or `keyring`.
</ResponseField>

<ResponseField name="effective_encryption_source" type="string">
  The effective master-key source chosen at runtime, for example `env`, `keyring`, or `local_key`.
</ResponseField>

<ResponseField name="encryption_backend" type="string">
  Human-readable description of the effective master-key source.
</ResponseField>

### `GET /api/ready`

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

<ResponseField name="status" type="string" required>
  Overall readiness: `"ready"` when all checks pass, `"not_ready"` when `issues` is non-empty.
</ResponseField>

<ResponseField name="checks" type="object" required>
  Per-component status.

  <Expandable title="checks fields">
    <ResponseField name="store" type="string" required>
      `"ok"` if the relational store opens and passes a health probe. Failures: `"failed"`.
    </ResponseField>

    <ResponseField name="vault" type="string" required>
      `"ok"` if the encrypted KV store accepts a read/write roundtrip. Failures: `"failed"`.
    </ResponseField>

    <ResponseField name="integrity" type="string" required>
      `"ok"` if the vault integrity check succeeds. Failures: `"failed"`.
    </ResponseField>

    <ResponseField name="identity" type="string" required>
      `"ok"` if the caller's identity is registered.
    </ResponseField>

    <ResponseField name="providers" type="string" required>
      `"ok"` if every bundled and custom provider definition parses. Failures: `"failed"`.
    </ResponseField>

    <ResponseField name="connections" type="string" required>
      `"ok"` if connection records load for the active vault. Failures: `"failed"`.
    </ResponseField>

    <ResponseField name="spec_version" type="string" required>
      `"ok"` if the server config schema version matches.
    </ResponseField>

    <ResponseField name="redis" type="string">
      Present when Redis is configured. `"ok"` after a successful ping.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="warnings" type="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.
</ResponseField>

<ResponseField name="issues" type="string[]">
  Fatal problems. When non-empty, `status` is `"not_ready"`. Each entry is a human-readable string suitable for surfacing in a monitoring alert.
</ResponseField>

<ResponseField name="configured_encryption_mode" type="string">
  The configured master-key resolution mode.
</ResponseField>

<ResponseField name="effective_encryption_source" type="string">
  The effective master-key source chosen at runtime, for example `env`, `keyring`, or `local_key`.
</ResponseField>

<ResponseField name="encryption_backend" type="string">
  Human-readable description of the effective master-key source.
</ResponseField>

### `GET /api/whoami`

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

<ResponseField name="home" type="string" required>
  Absolute path to the authsome home directory.
</ResponseField>

<ResponseField name="identity" type="string" required>
  Registered identity handle.
</ResponseField>

<ResponseField name="principal_id" type="string">
  Opaque Principal identifier when the identity claim is accepted.
</ResponseField>

<ResponseField name="vault_id" type="string">
  Opaque Vault identifier for the active credential store.
</ResponseField>

<ResponseField name="principal_role" type="string">
  `admin` or `user`.
</ResponseField>

<ResponseField name="did" type="string">
  The identity's `did:key` URI.
</ResponseField>

## 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](/security/daemon-trust-boundary) for the trust model.

## Calling the API directly

Unauthenticated liveness:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
curl -s http://127.0.0.1:7998/openapi.json | jq '.paths | keys'
```

## What's next

<Columns cols={2}>
  <Card title="The local daemon" icon="server" href="/concepts/the-daemon">
    Lifecycle, routes, and v1 limitations.
  </Card>

  <Card title="Daemon trust boundary" icon="shield" href="/security/daemon-trust-boundary">
    What loopback-only access control protects against.
  </Card>

  <Card title="Daemon issues" icon="wrench" href="/troubleshooting/daemon-issues">
    Port conflicts, lost sessions, and restart behavior.
  </Card>

  <Card title="Environment variables" icon="terminal" href="/reference/environment-variables">
    `AUTHSOME_BASE_URL` and `AUTHSOME_HOME`.
  </Card>
</Columns>