The REST API

Every board, sync, and widget in Deckgauge is served by one Fastify API — the same one the web app and the MCP server call. This page covers how to authenticate against it, what a request and an error look like, and a grouped map of what's there.

Same request, with and without board access.

What it does, and where the data comes from

This is the web app's own backend (apps/api), not a separately productized public API. It's read here because the same routes are what the MCP server sits in front of, and because a board's front end is only one client of it. In local development it listens on http://localhost:3001 by default — that default comes from the API's own PORT environment variable, which isn't actually documented in .env.example. Don't confuse that with API_URL: that's a separate variable the web app reads to know where to reach the API, not what the API listens on — it also defaults to http://localhost:3001 when unset, which is why the two are easy to conflate. Routes are mounted at the API's root with no version prefix, so a board's routes look like /boards/:id, not /v1/boards/:id.

Authentication

The web app signs you in through NextAuth's Keycloak OIDC flow and attaches the resulting access token to every API call as Authorization: Bearer <token>. On the API side, a Fastify preHandler verifies that JWT's RS256 signature against Keycloak's JWKS endpoint and checks its issuer, then resolves the token's subject claim to a local User row (creating one on first sign-in) that every route reads as request.user. That verification step doesn't reject a request by itself — a missing or invalid token just means no request.user gets set.

A second, separate check does the rejecting: every route declares an authorization policy (public, authenticated, a board or roadmap role, comparison, or connection ownership — see Access control), and the API refuses to start at all if a route doesn't declare one. A preHandler evaluates that policy on every request: no valid token answers 401; a valid token that doesn't meet the policy — wrong board role, not the resource's creator, someone else's connection — answers 403. Only routes declared public, such as the health check, accept a request with no token at all.

There's no separate API key or client-credentials flow today — the only way to obtain a token is to complete the web login and reuse the JWT it gives you. Treat this as an authenticated app backend you can script against with a browser-obtained token, not an API designed for arms-length third-party integration.

Board-scoped authorization

Most routes hang off a specific board and require a BoardAccess row for the calling user at or above a minimum role — Viewer, Editor, or Owner, ranked in that order. A user with no row for that board gets 403; the check runs fresh on every request, not once per session. See Access control for how those roles are granted.

Not every route is board-scoped, though. Org trees and employee boards use the same Viewer/Editor/Owner model as boards, just on a per-tree OrgTreeAccess row instead of a per-board one — listing your own trees and creating a new one only require being signed in, since those routes filter or stamp ownership themselves rather than checking a role up front. Engineering-intelligence and timesheet reads instead check a Keycloak realm role (cockpit-analytics) — timesheet reads check that role and Viewer on the org tree the request names, since only those carry a tree id. Comparisons check that the caller created the comparison, not a role. Provider-connection writes (Jira, GitHub, GitLab, and Azure DevOps instances) check that the caller created the connection — any signed-in user may create one, and a connection that predates this model has no owner until whoever edits it first claims it. A handful of other resources, such as editing a project sync's board-facing settings, still only require being signed in, with no per-resource role at all. Each of these still answers 401/403 the same way; only what counts as "authorized" differs. See Access control for the full breakdown.

Request & response conventions

Request bodies and query strings are validated with Zod schemas from packages/shared/src — the same schemas the web app's forms use, so client and server agree on shape. A failing validation returns 400 with the parsed Zod error, for example {"error": {"fieldErrors": {...}, "formErrors": [...]}}, so the failing field is named rather than guessed at. Authentication and access failures return a flat {"error": "<message>"} instead (for example {"error": "Forbidden"}). Successful responses return the resource itself with no wrapping envelope — 200/201 with a body, or 204 with none for most deletes and simple updates.

Route families

Grouped by what they act on, not enumerated endpoint by endpoint — each family holds several routes under a shared prefix.

If it looks wrong

Related

• The MCP server — the read-only tool surface built on top of these same routes.
• Access control — how Viewer/Editor/Owner roles are granted.
• Keycloak and identity providers — where the JWT this API verifies comes from.
• Connecting data sources — the shared-connection and board-source model behind the provider route families.

Last updated 17 August 2026