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 |
Make a key
Section titled “Make a key”-
Open the user menu (top right) and choose API keys.
-
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.
-
Select Create key, then copy the key now — it is shown only once.
With your session or a JWT (see Overview), never with a key or a room token:
curl -X POST "$API/api/users/me/api-tokens" \ -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \ -d '{"name":"field-app","permissions":["read","write"],"expiresInDays":90}'# → 201 { "id": "…", "token": "cmap_u_…", "name": "field-app", "permissions": ["read","write"],# "roomIds": null, "expiresAt": "…" }Add "roomIds": ["<roomId>", …] to limit the key to rooms you are a member of (at most 100). List your
keys, without their secrets, with GET /api/users/me/api-tokens; revoke one with
DELETE /api/users/me/api-tokens/<id>.
The rules
Section titled “The rules”- 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
writekey 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.
Permissions
Section titled “Permissions”| 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.
Account-level routes
Section titled “Account-level routes”| 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) |
export API=https://app.collmap.comAUTH="Authorization: Bearer cmap_u_…" # your key
# The rooms the key reachescurl -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 .What a key can never do
Section titled “What a key can never do”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.
Credit
Section titled “Credit”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.