# Self-host the account server

> Run QuickDesk's account and API server (login/SSO, address book, device registry, audit, and recording) on your own infrastructure.

The **account server** is QuickDesk's HTTPS control plane. It handles
everything that is not the live desktop stream. Clients ship with a default
server. A single
[client setting](/modalities/quickdesk/clients#point-clients-at-your-relay--account-server)
points them at your own deployment for a fully in-house remote-access product.

> **NOTE:**
> The account server carries **no pixels**. The desktop session is encrypted
> end to end over the [QUIC relay](/modalities/quickdesk/how-it-works). The
> account server handles identity, the address book, device state, and the
> audit / recording trail.

## What the account server does

  - **Login & SSO** — Password login plus OIDC single sign-on. A QuickDesk session is an
    ordinary session from your identity provider. The client holds a
    short-lived bearer token, not your credentials.
  - **Address book** — A personal, per-user directory of devices and tags. Operators reconnect
    by name instead of by id.
  - **Device registry** — Devices register on boot with a heartbeat and system info. The registry
    tracks which devices are online. An operator can disconnect a device.
  - **Audit & recording** — A log of connection sessions and file transfers, plus optional server-side
    session recording for compliance.

## API surface

The server implements the surface that the clients call directly:
bearer-authenticated JSON over HTTPS.

| Area | Routes | Notes |
| --- | --- | --- |
| **Auth** | `/api/login`, `/api/currentUser`, `/api/logout`, `/api/login-options` | Password + OIDC; returns a bearer access token. |
| **SSO** | `/api/oidc/auth`, `/api/oidc/callback`, `/api/oidc/auth-query` | Poll-based OIDC bridge onto a redirect-flow provider. |
| **Devices** | `/api/heartbeat`, `/api/sysinfo` | Token-less; keyed by device id. Boxes register before a user logs in. |
| **Address book** | `/api/ab/*` | Personal directory: peers, tags, settings. |
| **Audit** | `/api/audit/conn`, `/api/audit/file` | Session and file-transfer logs. Loss-tolerant. |
| **Recording** | `/api/record` | Chunked upload of session recordings. |

> **NOTE:**
> The device heartbeat, sysinfo, and audit routes are intentionally
> **token-less**. A box registers and reports before any user signs in on it.
> These routes are keyed by device id. The account server's device gate secures
> them.

## Backing services (by role)

The server is stateless. Supply one of each of these standard roles. None is
QuickDesk-specific. Use the services that you already run:

| Role | Used for |
| --- | --- |
| **Identity provider (OIDC)** | Login and SSO. QuickDesk sessions are provider sessions; the server verifies bearer tokens against it. |
| **Relational database** | Device registry and the personal address book. |
| **S3-compatible object storage** | Session recordings. |
| **Columnar / analytics store** | Connection and file-transfer audit logs (high-volume, append-only). |
| **Key-value cache** | Device online-presence markers and operator disconnect signals (short TTL). |

## Deploy

  1. **Provision the backing roles**
Start the identity, database, object storage, analytics store, and cache
    roles, or point at existing ones. Load the QuickDesk schema into the
    database and the analytics store.
  2. **Configure the server**
Set the connection details for each backing role. Set your identity
    provider's issuer. Set the object-storage endpoint and bucket for
    recordings.
  3. **Put it behind TLS on a stable host**
Terminate HTTPS on a hostname that your clients will use as their
    **account server**, for example a dedicated admin subdomain. Allow a
    large request body on `/api/record` (recordings upload in chunks).
    Disable request buffering on that route.
  4. **Repoint the clients**
Set the clients' **account server** to your host. Preset it in a managed
    fleet, or set it per machine. New sessions then authenticate, audit, and
    record against your deployment.

## Single sign-on

QuickDesk uses a **poll-based** login flow. The server bridges the flow onto
a standard OIDC redirect provider. Thus the native client does no fragment
handling.

  1. **Enable a provider on your identity server**
Turn on an external OIDC provider. Add your account server's callback URL
    to the provider's redirect allow-list.
  2. **Client starts auth**
The client calls `/api/oidc/auth`. The server mints a correlation id,
    stores a PKCE verifier, and returns the provider authorize URL.
  3. **Provider redirects back, client polls**
After the user signs in, the provider redirects to `/api/oidc/callback`.
    The server exchanges the code and stores the session. The client polls
    `/api/oidc/auth-query` with the correlation id and receives its bearer
    token.

> **NOTE:**
> You manage providers on your **identity server**, not in QuickDesk. When you
> enable or disable a provider, `/api/login-options` shows the change with no
> client or server redeploy.

## Related

- [Operator console](/modalities/quickdesk/operator-console) — the web admin over this data
- [Security & audit](/modalities/quickdesk/security) — what is logged and how it is protected
- [Clients & downloads](/modalities/quickdesk/clients#point-clients-at-your-relay--account-server) — repointing clients