# Users

> Your app's users as Beekon sees them — list them, read one, list a user's devices, and erase everything a project holds under a user id (users:read, users:write).

Source: https://docs.getbeekon.com/api/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](https://docs.getbeekon.com/start/concepts/#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`

**Scope:** `users:read` · Lists the project’s users, [paged](https://docs.getbeekon.com/api/pagination/), in byte order of `user_id`. There are no filters.

```sh
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`:

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

## GET `/v1/users/{user_id}`

**Scope:** `users:read` · Reads one user.

```sh
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

```json
{
  "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](#a-users-devices).

## 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

### GET `/v1/users/{user_id}/devices`

**Scope:** `users:read` · The devices whose current user is this user, as [device objects](https://docs.getbeekon.com/api/devices/#the-device-object), 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

### 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.                                                                             |

```sh
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.

Erasure cannot be undone

`users:write` erases data. Give it only to the backend service that handles deletion requests.

## 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.                                                                                                                        |
