API Overview & Authentication

CollMap has a RESTful HTTP API (built with Fastify) for managing rooms, markers, layers, uploads, comments, and exports. Anything you can do in the app you can largely do over HTTP — most usefully, driving a single room from a script with a room-scoped token.

Base URL

All endpoints are served from the app origin:

https://collmap.com

(Running the stack locally, the API server is at http://localhost:3001.)

Two ways to authenticate

Every protected endpoint takes a bearer token in the Authorization header:

Authorization: Bearer <token>

There are two kinds of token:

1. A user session (JWT)

For acting as yourself — everything your account can do, including owner-only operations (create / delete / rename rooms, invite members, mint API tokens, read your account). A signed-in browser session exchanges its OIDC cookie for a short-lived JWT:

GET /api/auth/token

→ { "token": "<jwt>" }. The JWT is short-lived and refreshed automatically in the app.

The session cookie counts as identity too

Owner-only endpoints accept either a bearer JWT or the signed-in session cookie, so a fetch(..., { credentials: 'include' }) from the browser works without the /api/auth/token hop. The JWT exists for callers that hold no cookie jar — scripts, CI, external tools.

2. A room API token (cmap_…)

For scripts and external tools that push data into (or pull it from) one room, with no browser session. You mint it once as the room owner and use it directly. Room tokens are room-scoped and limited to data operations — see Room API Tokens.

Note

A room token acts as its creating owner for attribution and storage quota, but is never granted the owner’s role: it can’t delete/rename a room, invite members, mint tokens, or read your account. Data it writes is attributed to api-token:<name>.

Token scoping is fail-closed

A room token is accepted only on the room-scoped data endpoints it’s explicitly allowed to reach. Present it anywhere else and the request is rejected with 403 api_token_not_allowed — by design. A token used against a different room, or without the required permission, likewise gets a 403. The full allowlist is on the Room API Tokens page.

WebSocket

Real-time collaboration runs over a separate Yjs WebSocket (wss://collmap.com/ws). The WebSocket is JWT-only — API tokens have no WebSocket path; token writes reach the live document through the REST endpoints and propagate from there.

Where to next

Room API TokensMint a token, permissions, and the full allowlist.

Quick Start (cURL)Copy-paste your way through a room over HTTP.

ReferenceEvery endpoint, grouped by resource.

Errors & LimitsStatus codes, quota errors, and rate limits.