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).
The machine-readable description is 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.
Base URL: one host per region
Section titled “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:
https://api.<cell>.getbeekon.comYou 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
Section titled “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 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, 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
Section titled “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.
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.
Every endpoint
Section titled “Every endpoint”| Method and path | Scope | Page |
|---|---|---|
POST /v1/token | none (takes the key) | Authentication |
GET /v1/project | project:read | Project |
GET /v1/devices | devices:read | Devices |
GET /v1/devices/{install_id} | devices:read | Devices |
POST /v1/devices/{install_id}/commands | devices:write | Devices |
GET /v1/users | users:read | Users |
GET /v1/users/{user_id} | users:read | Users |
GET /v1/users/{user_id}/devices | users:read | Users |
DELETE /v1/users/{user_id} | users:write | Users |
GET /v1/locations | locations:read | Locations |
GET /v1/locations/feed | locations:read | Locations |
POST /v1/ingest | locations:write | Ingest |
GET /v1/trips | trips:read | Trips |
GET /v1/trips/{trip_id} | trips:read | Trips |
GET /v1/trips/{trip_id}/points | trips:read | Trips |
GET /v1/geofences | geofences:read | Geofences |
POST /v1/geofences | geofences:write | Geofences |
GET /v1/geofences/{fence_id} | geofences:read | Geofences |
PUT /v1/geofences/{fence_id} | geofences:write | Geofences |
DELETE /v1/geofences/{fence_id} | geofences:write | Geofences |
GET /v1/config/document | config:read | Remote config |
PUT /v1/config/document | config:write | 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 |
GET /v1/webhooks | webhooks:read | Webhooks |
POST /v1/webhooks | webhooks:write | Webhooks |
GET /v1/webhooks/{webhook_id} | webhooks:read | Webhooks |
PATCH /v1/webhooks/{webhook_id} | webhooks:write | Webhooks |
DELETE /v1/webhooks/{webhook_id} | webhooks:write | Webhooks |
POST /v1/webhooks/{webhook_id}/rotate-secret | webhooks:write | Webhooks |
POST /v1/webhooks/{webhook_id}/ping | webhooks:write | Webhooks |
Conventions in brief
Section titled “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 asnext_cursor. - One error shape:
{"error":"<text>"}. See Errors. - Cursor paging on every list:
limit1–500 and an opaquecursor. See Pagination.
The full set is on Conventions.
Versioning
Section titled “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, never shipped silently.