Skip to content

Users

These endpoints list your app’s users, read one, list a user’s devices, and erase everything the project stores under a user id.

A user is a user id your app set with setUserId that at least one stored location carries. Beekon learns users only from uploaded locations (there is no create call and no profile) and returns each id exactly as the SDK sent it, so send an opaque database key, never an email or phone number (Choosing a user id). Locations with no user id make no user. A user exists while the project stores at least one of its locations; once they have all aged out or been erased, the user leaves the list and reading it answers 404.

Scope: users:read · Lists the project’s users, paged, in byte order of user_id. There are no filters.

Terminal window
curl -s -G https://api.in1.getbeekon.com/v1/users \
-H "Authorization: Bearer $BEEKON_TOKEN" \
--data-urlencode "limit=100"
ParameterRequiredMeaning
limitno1–500, default 100.
cursornoThe previous page’s next_cursor (prefix us1_, at most 356 bytes).

Response 200:

{
"next_cursor": null,
"users": [
{"last_seen": "2026-10-15T09:30:00.123Z", "user_id": "customer-42"}
]
}

Scope: users:read · Reads one user.

Terminal window
curl -s https://api.in1.getbeekon.com/v1/users/customer-42 \
-H "Authorization: Bearer $BEEKON_TOKEN"

Response 200: {"user":{…}}. An id that is not a user of this project (never seen, aged out, erased, or another project’s) is 404 not found.

{
"last_seen": "2026-10-15T09:30:00.123Z",
"user_id": "customer-42"
}
MemberTypeMeaning
user_idstringThe id, exactly as your app set it.
last_seenstringThe recorded time of the newest stored location that carries this id, on any device.

Both members are always present. There is no device count or device list on the object; use a user’s devices.

The id is opaque text. Percent-encode it as one path segment, the same way as an install_id: a%2Fb is the user a/b. After decoding it must be 1–256 bytes of valid UTF-8 with no control characters, or the request is 400 invalid_user_id. Ids are compared byte for byte: never trimmed, case-folded or normalised. A user whose id is exactly . or .. cannot be addressed by path; it is still listed.

Beekon’s own logs for these endpoints record the route, never the id.

Scope: users:read · The devices whose current user is this user, as device objects, paged and ordered by install_id. It returns exactly what GET /v1/devices?user_id=<user_id> returns, and a cursor from one resumes on the other.

A device’s current user is the user id on its newest admitted location, so a device moves to another user only when your app calls setUserId with another id. A user that exists but has no current device is an empty page; an id that is not a user of this project is 404 not found.

ParameterRequiredMeaning
limitno1–500, default 100.
cursornoThe previous page’s next_cursor (prefix dc1_).

Response 200: {"devices":[…],"next_cursor":null}.

Scope: users:write · Erases everything this project holds under the user id: its stored locations (gated or not), set-aside uploads, events and their pending webhook deliveries, device geofence events, trips, and queued work that carries the id. Devices whose current user is this id get user_id: null. The same id in another project or organisation is untouched, and the user’s former devices are still listed.

Erasure runs in steps, with two passes around a settle window of about three minutes. Repeat the same DELETE until it answers 204:

StatusMeaning
202 {"status":"erasing"}Work is left, or the settle window is running. Wait Retry-After seconds (1 to 185), then call again.
204Done: the second pass, after the window, found nothing in this project under the id. No body.
429 rate limitedMore than 30 calls a minute from this key. Wait Retry-After.
503 unavailable, retryAnother erasure is running in this project. Wait Retry-After (1 s).
500 internal errorA step failed. Call again.
Terminal window
while :; do
code=$(curl -s -o /dev/null -w '%{http_code}' -D headers.txt -X DELETE \
https://api.in1.getbeekon.com/v1/users/customer-42 \
-H "Authorization: Bearer $BEEKON_TOKEN")
[ "$code" = 204 ] && break
wait=$(awk 'tolower($1)=="retry-after:" {print $2+0}' headers.txt)
sleep "${wait:-1}"
done
  • Every valid id ends at 204, including one with no data and one already erased, so the answer does not tell you whether the user existed.
  • A 204 is not a block list. Locations still queued on a device, or recorded later, create the user again. Stop the id at its source first (your app calls setUserId(null), or the device stops and its queue drains), then erase.
  • A refused call (429, 503) erases nothing. Each call that did work is recorded in the organisation’s audit log with a keyed hash of the id, never the id itself.
StatuserrorWhen
400invalid_user_idThe path id is over 256 bytes, not valid UTF-8, or contains a control character. Checked before any read.
400limit must be an integer in [1, 500] · invalid_cursor · cursor_query_mismatchBad paging, or a cursor from another project or filter.
401missing bearer token · invalid session tokenNo valid session.
403server credentials requiredThe token was minted from an SDK key.
403insufficient scopeThe key lacks users:read (reads) or users:write (erase). Neither implies the other, and devices:* reaches no users endpoint.
404not foundAn id that is not a user of this project (reads only; erase always converges to 204).
405method_not_allowedAny other method. Allow is GET, HEAD on /v1/users and …/devices, and DELETE, GET, HEAD on /v1/users/{user_id}.
429rate limitedErase only.
500internal errorA failure on our side. Retry.
503unavailable, retryErase only.