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
Section titled “Base URL”All endpoints are served from the app origin:
https://app.collmap.com(Running the stack locally, the API server is at http://localhost:3001.)
A room token or personal key works only on the app it was made in, so call the API at
app.collmap.com. collmap.com without app. answers with an older API that has no personal keys.
Three ways to authenticate
Section titled “Three ways to authenticate”Every protected endpoint takes a bearer token in the Authorization header:
Authorization: Bearer <token>There are three kinds of token:
1. A user session (JWT)
Section titled “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.
2. A room API token (cmap_…)
Section titled “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.
3. A personal API key (cmap_u_…)
Section titled “3. A personal API key (cmap_u_…)”For a script or an AI-assistant connector that works as you across your rooms, not in one room only. You make it yourself from the user menu (API keys). It reaches the rooms you are a member of, or only the ones you choose, with at most your own rights in each. It can also list your rooms, read your profile and usage, and create a room — see Personal API Keys.
Token scoping is fail-closed
Section titled “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.
A personal key is fail-closed the same way: it is accepted on those same endpoints, in the rooms it reaches, plus four account-level routes listed on Personal API Keys, and refused everywhere else.
WebSocket
Section titled “WebSocket”Real-time collaboration runs over a separate Yjs WebSocket (wss://app.collmap.com/ws). The
WebSocket is JWT-only — room tokens and personal keys have no WebSocket path; their writes reach
the live document through the REST endpoints and propagate from there.