# Server API overview

> The Beekon Cloud /v1 server API — base URLs per region, server keys versus SDK keys, how to get a session token, every endpoint and its scope, and the versioning promise.

Source: https://docs.getbeekon.com/api/

The Beekon Cloud **server API** lets your own backend read and manage a project over HTTPS: the project itself, devices and the commands you send them, your app’s users, location history (and uploading locations from your server), trips, geofences, remote configuration, the event log and webhook endpoints. It is a plain JSON-over-HTTP API under `/v1`, authenticated with a **server key**. Where a path or field name says “point” (such as `/points` or `point_count`), it means a stored location (see [Concepts](https://docs.getbeekon.com/start/concepts/)).

The machine-readable description is [`openapi.yaml`](https://docs.getbeekon.com/openapi.yaml) (OpenAPI 3.1). It describes the same endpoints, parameters and responses as these pages. It leaves out the device-only endpoints and the webhook delivery request. For the delivery and its headers, see [Webhooks](https://docs.getbeekon.com/api/webhooks/#the-delivery-request).

## Base URL: one host per region

Every Beekon project lives in one region (a **cell**). Each region has its own API host, and you call the host of the region your project lives in:

```plaintext
https://api.<cell>.getbeekon.com
```

You never need to look the cell up: it is the second segment of your key. A server key `bkserv_in1_…` belongs to cell `in1`, so its base URL is `https://api.in1.getbeekon.com`. There is no global host that forwards to the right region. A key presented to another region’s host is refused with `401`, exactly like an unknown key.

The host is the only part that changes. If you were given another base URL (a staging host you were told to use), send the same `/v1` paths to that host instead, for example `http://localhost:8080/v1/token`. The examples on these pages use the Cloud host.

Each host also answers `GET /healthz` and `GET /readyz`: unauthenticated liveness and readiness checks with minimal bodies. They are not part of `/v1`.

## Two kinds of key

|             | SDK (project) key                    | Server key                                                |
| ----------- | ------------------------------------ | --------------------------------------------------------- |
| Prefix      | `bkproj_<cell>_…`                    | `bkserv_<cell>_…`                                         |
| Lives in    | your mobile app                      | **your backend only**. Never ship it in an app.           |
| Used for    | the SDK’s uploads and config polling | this API                                                  |
| Permissions | the device endpoints the SDK needs   | the [scopes](https://docs.getbeekon.com/api/scopes/) chosen when the key was issued |

Both kinds are exchanged for a short-lived **session token** at the same endpoint. You send the session token, never the key, on every other call. A session minted from an SDK key is refused by every server endpoint (`403`) except [`POST /v1/ingest`](https://docs.getbeekon.com/api/ingest/), where the SDK uploads its locations. A session minted from a server key is refused by the device-only endpoints.

Server keys are issued per project by a project owner or admin. The scopes are fixed at issue: to change them, issue a new key with the scopes you want and revoke the old one.

## Getting a token

Every example on these pages uses the same placeholder key and region, `bkserv_in1_…` on `api.in1.getbeekon.com`. Replace both with your own.

```sh
export BEEKON_SERVER_KEY='bkserv_in1_REPLACE_WITH_YOUR_SECRET'
export BEEKON_TOKEN=$(curl -s -X POST https://api.in1.getbeekon.com/v1/token \
  -H "Authorization: Bearer $BEEKON_SERVER_KEY" | jq -r .access_token)
```

The response is `{"access_token":"eyJhbGciOiJFUzI1NiIs…","expires_in":3600}`. Send `Authorization: Bearer $BEEKON_TOKEN` on every other `/v1` call. Mint a new token when it expires or when a call answers `401`. See [Authentication](https://docs.getbeekon.com/api/authentication/).

## Every endpoint

| Method and path                                | Scope                | Page                                                                                                |
| ---------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------- |
| `POST /v1/token`                               | none (takes the key) | [Authentication](https://docs.getbeekon.com/api/authentication/)                                                              |
| `GET /v1/project`                              | `project:read`       | [Project](https://docs.getbeekon.com/api/project/)                                                                            |
| `GET /v1/devices`                              | `devices:read`       | [Devices](https://docs.getbeekon.com/api/devices/)                                                                            |
| `GET /v1/devices/{install_id}`                 | `devices:read`       | [Devices](https://docs.getbeekon.com/api/devices/)                                                                            |
| `POST /v1/devices/{install_id}/commands`       | `devices:write`      | [Devices](https://docs.getbeekon.com/api/devices/#send-a-command)                                                             |
| `GET /v1/users`                                | `users:read`         | [Users](https://docs.getbeekon.com/api/users/)                                                                                |
| `GET /v1/users/{user_id}`                      | `users:read`         | [Users](https://docs.getbeekon.com/api/users/)                                                                                |
| `GET /v1/users/{user_id}/devices`              | `users:read`         | [Users](https://docs.getbeekon.com/api/users/#a-users-devices)                                                                |
| `DELETE /v1/users/{user_id}`                   | `users:write`        | [Users](https://docs.getbeekon.com/api/users/#erase-a-user)                                                                   |
| `GET /v1/locations`                            | `locations:read`     | [Locations](https://docs.getbeekon.com/api/locations/)                                                                        |
| `GET /v1/locations/feed`                       | `locations:read`     | [Locations](https://docs.getbeekon.com/api/locations/#get-v1locationsfeed)                                                    |
| `POST /v1/ingest`                              | `locations:write`    | [Ingest](https://docs.getbeekon.com/api/ingest/)                                                                              |
| `GET /v1/trips`                                | `trips:read`         | [Trips](https://docs.getbeekon.com/api/trips/)                                                                                |
| `GET /v1/trips/{trip_id}`                      | `trips:read`         | [Trips](https://docs.getbeekon.com/api/trips/)                                                                                |
| `GET /v1/trips/{trip_id}/points`               | `trips:read`         | [Trips](https://docs.getbeekon.com/api/trips/#a-trips-locations)                                                              |
| `GET /v1/geofences`                            | `geofences:read`     | [Geofences](https://docs.getbeekon.com/api/geofences/)                                                                        |
| `POST /v1/geofences`                           | `geofences:write`    | [Geofences](https://docs.getbeekon.com/api/geofences/)                                                                        |
| `GET /v1/geofences/{fence_id}`                 | `geofences:read`     | [Geofences](https://docs.getbeekon.com/api/geofences/)                                                                        |
| `PUT /v1/geofences/{fence_id}`                 | `geofences:write`    | [Geofences](https://docs.getbeekon.com/api/geofences/)                                                                        |
| `DELETE /v1/geofences/{fence_id}`              | `geofences:write`    | [Geofences](https://docs.getbeekon.com/api/geofences/)                                                                        |
| `GET /v1/config/document`                      | `config:read`        | [Remote config](https://docs.getbeekon.com/api/remote-config/)                                                                |
| `PUT /v1/config/document`                      | `config:write`       | [Remote config](https://docs.getbeekon.com/api/remote-config/)                                                                |
| `GET /v1/config`                               | `config:read`        | The SDK’s own config fetch, not part of this API. From your server, read `GET /v1/config/document`. |
| `GET /v1/events`                               | `events:read`        | [Events](https://docs.getbeekon.com/api/events/)                                                                              |
| `GET /v1/webhooks`                             | `webhooks:read`      | [Webhooks](https://docs.getbeekon.com/api/webhooks/)                                                                          |
| `POST /v1/webhooks`                            | `webhooks:write`     | [Webhooks](https://docs.getbeekon.com/api/webhooks/)                                                                          |
| `GET /v1/webhooks/{webhook_id}`                | `webhooks:read`      | [Webhooks](https://docs.getbeekon.com/api/webhooks/)                                                                          |
| `PATCH /v1/webhooks/{webhook_id}`              | `webhooks:write`     | [Webhooks](https://docs.getbeekon.com/api/webhooks/)                                                                          |
| `DELETE /v1/webhooks/{webhook_id}`             | `webhooks:write`     | [Webhooks](https://docs.getbeekon.com/api/webhooks/)                                                                          |
| `POST /v1/webhooks/{webhook_id}/rotate-secret` | `webhooks:write`     | [Webhooks](https://docs.getbeekon.com/api/webhooks/#rotate-the-secret)                                                        |
| `POST /v1/webhooks/{webhook_id}/ping`          | `webhooks:write`     | [Webhooks](https://docs.getbeekon.com/api/webhooks/#send-a-test-ping)                                                         |

## Conventions in brief

* **JSON in, JSON out.** Timestamps are RFC 3339 UTC with exactly three fractional digits (`2026-10-07T06:30:00.000Z`).
* **The project comes from the token.** No path, query parameter or body names a project. Query parameters an endpoint does not define, including `project_id`, are ignored.
* **Optional members are omitted**, never `null`, except the members documented as nullable, such as `next_cursor`.
* **One error shape**: `{"error":"<text>"}`. See [Errors](https://docs.getbeekon.com/api/errors/).
* **Cursor paging** on every list: `limit` 1–500 and an opaque `cursor`. See [Pagination](https://docs.getbeekon.com/api/pagination/).

The full set is on [Conventions](https://docs.getbeekon.com/api/conventions/).

## Versioning

The path version `/v1` is a promise: within `/v1` we only make **additive** changes: new endpoints, new optional members, new enum values and new event types. Your client must ignore response members and enum values it does not recognise. Removing or renaming a member, changing a member’s type, or changing the meaning of an existing value is a breaking change. It ships under a new version, never silently under `/v1`.

The locations page and event payloads also carry a `schema_version` (currently `1`). It changes only on a breaking change to that document. If you meet a `schema_version` you do not understand, fail loudly rather than parsing optimistically.

Beekon is pre-1.0: until 1.0, a breaking change to `/v1` remains possible. It is announced in the [changelog](https://docs.getbeekon.com/api/changelog/), never shipped silently.

## Pages

[Quickstart ](https://docs.getbeekon.com/api/quickstart/)Server key → token → project → a page of locations, with curl.

[Authentication ](https://docs.getbeekon.com/api/authentication/)Token exchange, expiry and re-minting.

[Scopes ](https://docs.getbeekon.com/api/scopes/)The 15 permissions a server key can carry.

[Conventions ](https://docs.getbeekon.com/api/conventions/)Formats, timestamps, ids, bodies, retries and idempotency.

[Errors ](https://docs.getbeekon.com/api/errors/)The error envelope, every status and every token.

[Pagination ](https://docs.getbeekon.com/api/pagination/)limit, cursors, and how a walk ends.

[Rate limits ](https://docs.getbeekon.com/api/rate-limits/)429, Retry-After and the published limits.

[Project ](https://docs.getbeekon.com/api/project/)GET /v1/project

[Devices ](https://docs.getbeekon.com/api/devices/)List and read devices, send them commands.

[Users ](https://docs.getbeekon.com/api/users/)Your app's users, their devices, and erasing a user.

[Locations ](https://docs.getbeekon.com/api/locations/)GET /v1/locations and the arrival-ordered GET /v1/locations/feed

[Ingest ](https://docs.getbeekon.com/api/ingest/)POST /v1/ingest: upload locations from your server.

[Location mode ](https://docs.getbeekon.com/api/location-mode/)The normalised movement mode on locations and trips.

[Trips ](https://docs.getbeekon.com/api/trips/)Server-detected trips and their locations.

[Geofences ](https://docs.getbeekon.com/api/geofences/)Create, read, replace and delete geofences.

[Remote config ](https://docs.getbeekon.com/api/remote-config/)Read and replace the config document.

[Events ](https://docs.getbeekon.com/api/events/)GET /v1/events and the event types.

[Webhooks ](https://docs.getbeekon.com/api/webhooks/)Webhook endpoints, delivery, signatures, rotation and ping.

[Changelog ](https://docs.getbeekon.com/api/changelog/)What changed in the server API.
