Auth API

The Auth API is how Alaf Server signs users in and keeps their session. Almost everything here is served by Better Auth through a single catch-all — email/password sign-in and sign-up, OAuth, the organization/member/invitation endpoints, and the MCP OAuth authorization server. A small set of desktop-only endpoints sit in front of it to bootstrap a zero-auth local session and hand off cloud sign-in to the downloadable app.

This module is consumed almost entirely by the dashboard (and, in desktop mode, the Electron host) — you rarely call it directly. For programmatic API access, mint a personal access token instead (alaf server token create) and use it as a bearer header. See the API overview and Auth & sessions for the full model.

Endpoints

These are plain Hono routes, not permission-tagged secure routes. The "Auth" column shows how each one is gated rather than a resource:action tag.

The Better Auth catch-all

The last route, GET|POST /api/auth/*, forwards the raw request to Better Auth's handler. Everything a normal sign-in flow needs lives here — there is no separate schema in this module because Better Auth owns the request and response shapes. The endpoints it serves (all under /api/auth) include:

• Credentials — POST /sign-in/email, POST /sign-up/email, POST /sign-out, POST /forget-password, POST /reset-password, POST /verify-email. Passwords are 8–128 chars; reset and verification emails only send when SMTP is configured.
• OAuth — POST /sign-in/social and GET /callback/:provider for GitHub and Google (each enabled only when its client ID/secret is set).
• Organizations — /organization/*: create, set-active, list, invite-member, accept-invitation, update-member-role, remove-member, leave, and more. Member-listing reads are additionally shielded so restricted/member roles can't read admin-tier data.
• MCP OAuth 2.1 — /mcp/authorize, /mcp/token, /mcp/register (dynamic client registration), /mcp/get-session, plus discovery at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource (also re-served at the origin root). See the MCP API.

Get the current session

GET /api/auth/get-session

Returns the active session and user as JSON, or 401 when unauthenticated. In zero-auth desktop mode (self-hosted onboarding, no password), a miss triggers an inline bootstrap: Alaf Server provisions the local admin user, mints a session, sets the cookie on the response, and returns it — so the dashboard's first navigation succeeds instead of looping to /login.

curl https://your-host/api/auth/get-session \
  -H "Cookie: alaf server.session_token=<session>"

Desktop session bootstrap

GET /api/auth/desktop-login mints a session for the zero-auth local admin and redirects to the dashboard. It is called once, right after self-hosted onboarding completes; if the instance isn't in zero-auth mode it redirects to /login instead. No request body.

Cloud sign-in handoff (desktop)

When the downloadable app signs in "with Cloud", the Electron host runs a PKCE flow and the API brokers it. The sequence is: register the nonce, open the system browser, poll, then claim.

POST /api/auth/desktop-auth-start

Guarded by the internal shared-token middleware — only the Electron host may register a nonce. Validated inline (there is no TypeBox schema module for auth); all three fields are required strings:

The remaining steps take query parameters, not bodies:

• GET /api/auth/cloud-callback?code=<code>&state=<state> — the cloud provider redirects here. With state it runs the desktop PKCE exchange and resolves the pending nonce; without state it runs the simpler browser exchange and sets the cookie directly. code is required.
• GET /api/auth/desktop-auth-poll?nonce=<nonce> — Electron polls until the status is resolved, then opens the claim URL. nonce is required.
• GET /api/auth/desktop-claim?code=<code> — exchanges the one-time claim code for a session cookie (set via the Set-Cookie header for cross-version Electron reliability) and redirects to the dashboard. code is required.

Errors you might see