Skip to content
EN

Personal API Keys

A personal API key (prefix cmap_u_) lets a script or an AI-assistant connector work as you in the rooms you are a member of, without a browser login and without one room token per room. It can also list your rooms, read your profile and storage usage, and create a room.

Room token (cmap_…) Personal key (cmap_u_…)
Made by the room’s owner, for one room you, for yourself
Reaches that one room every room you are a member of, or only the rooms you choose
Rights in a room the token’s permissions the key’s permissions, never more than your own role there
Account level nothing your rooms, your profile and usage, creating a room
  1. Open the user menu (top right) and choose API keys.

  2. Name the key, tick its permissions, choose when it expires (7 to 365 days, 90 by default), and choose All my rooms or Only these rooms.

  3. Select Create key, then copy the key now — it is shown only once.

  • Expiry is required: 1 to 365 days, 90 if you leave it out.
  • At most 10 active keys. An 11th answers 409 too_many_keys: revoke one first.
  • The room list is fixed when the key is made. To change it, revoke the key and make another. A room the key creates joins its list.
  • Your current role decides, on every request. Where you are a viewer, even a write key only reads; once you leave a room, the key loses it on its next request.
  • Public rooms you are not a member of stay closed to the key, even though anyone can open them in the browser.
  • Revoking a key, or its expiry, takes effect on the next request.
Permission Lets the key…
read List your rooms, read and export their data
write Add and change data, create rooms
upload Upload layer files

In a room, a key may call every endpoint a room token may call, with the same permission for each.

Route Needs Answers
GET /api/rooms read your rooms; only those on the key’s list if it has one
GET /api/users/me read { "user": { "userId", "username", "plan" }, "rooms": [...] }, never your email
GET /api/account/usage read your storage totals; the per-room list holds only the key’s rooms
POST /api/rooms/:roomId write creates the room, counted against your plan; an existing room is never changed (403)
Terminal window
export API=https://app.collmap.com
AUTH="Authorization: Bearer cmap_u_…" # your key
# The rooms the key reaches
curl -s "$API/api/rooms" -H "$AUTH" | jq '.[].name'
# Create a room: choose a new id of exactly 10 characters of [A-Za-z0-9_-]
curl -s -X POST "$API/api/rooms/aB3dEfGhIj" -H "$AUTH" \
-H "Content-Type: application/json" -d '{"name":"Survey 2026"}' | jq .

These answer 403 api_token_not_allowed, whatever the key’s permissions:

  • delete, clear or rename a room, or change its visibility or settings;
  • invite or remove members;
  • make, list or revoke keys or room tokens;
  • reach admin routes or the real-time WebSocket.

What a key writes is credited to you, with the key’s name beside it: the app shows “Jane · via field-app” on markers, layers, comments and the timeline. If your username can’t be shown (it is empty or holds an @), the app shows “User” and the start of your user id instead, as it does for everything you create: it never shows an email.