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.
GET /v1/users
Section titled “GET /v1/users”Scope: users:read · Lists the project’s users, paged, in byte order of
user_id. There are no filters.
curl -s -G https://api.in1.getbeekon.com/v1/users \ -H "Authorization: Bearer $BEEKON_TOKEN" \ --data-urlencode "limit=100"| Parameter | Required | Meaning |
|---|---|---|
limit | no | 1–500, default 100. |
cursor | no | The 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"} ]}GET /v1/users/{user_id}
Section titled “GET /v1/users/{user_id}”Scope: users:read · Reads one user.
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.
The user object
Section titled “The user object”{ "last_seen": "2026-10-15T09:30:00.123Z", "user_id": "customer-42"}| Member | Type | Meaning |
|---|---|---|
user_id | string | The id, exactly as your app set it. |
last_seen | string | The 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 {user_id} path segment
Section titled “The {user_id} path segment”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.
A user’s devices
Section titled “A user’s devices”GET /v1/users/{user_id}/devices
Section titled “GET /v1/users/{user_id}/devices”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.
| Parameter | Required | Meaning |
|---|---|---|
limit | no | 1–500, default 100. |
cursor | no | The previous page’s next_cursor (prefix dc1_). |
Response 200: {"devices":[…],"next_cursor":null}.
Erase a user
Section titled “Erase a user”DELETE /v1/users/{user_id}
Section titled “DELETE /v1/users/{user_id}”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:
| Status | Meaning |
|---|---|
202 {"status":"erasing"} | Work is left, or the settle window is running. Wait Retry-After seconds (1 to 185), then call again. |
204 | Done: the second pass, after the window, found nothing in this project under the id. No body. |
429 rate limited | More than 30 calls a minute from this key. Wait Retry-After. |
503 unavailable, retry | Another erasure is running in this project. Wait Retry-After (1 s). |
500 internal error | A step failed. Call again. |
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
204is 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 callssetUserId(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.
Errors
Section titled “Errors”| Status | error | When |
|---|---|---|
| 400 | invalid_user_id | The path id is over 256 bytes, not valid UTF-8, or contains a control character. Checked before any read. |
| 400 | limit must be an integer in [1, 500] · invalid_cursor · cursor_query_mismatch | Bad paging, or a cursor from another project or filter. |
| 401 | missing bearer token · invalid session token | No valid session. |
| 403 | server credentials required | The token was minted from an SDK key. |
| 403 | insufficient scope | The key lacks users:read (reads) or users:write (erase). Neither implies the other, and devices:* reaches no users endpoint. |
| 404 | not found | An id that is not a user of this project (reads only; erase always converges to 204). |
| 405 | method_not_allowed | Any other method. Allow is GET, HEAD on /v1/users and …/devices, and DELETE, GET, HEAD on /v1/users/{user_id}. |
| 429 | rate limited | Erase only. |
| 500 | internal error | A failure on our side. Retry. |
| 503 | unavailable, retry | Erase only. |