The Developers group holds what connects your app and your backend to the project. Owners and admins change it; members see it read-only.
API keys
Section titled “API keys”Two kinds of key, each in its own card. A key’s full value is shown once, when it is issued or rotated. Both carry the project’s region, so neither needs an endpoint setting, and a project can have several active keys of each kind. The Which key do I need? panel beside the cards says the same in short.
| Kind | Prefix | For |
|---|---|---|
| SDK keys | bkproj_ | Your app. Devices exchange it for a session to upload locations and fetch their config; it can’t call any server endpoint. See Cloud mode. |
| Server keys | bkserv_ | Your backend. It exchanges one at POST /v1/token for a session limited to the key’s scopes. Keep it on your server, never in an app. |
Issue key asks for the Kind, an optional Key name (up to 64 characters) and, for a server key, its Scopes:
| Module | Read | Write |
|---|---|---|
| Project | project:read | — |
| Devices | devices:read | devices:write (send commands to devices) |
| Locations | locations:read | locations:write (send locations, POST /v1/ingest) |
| Trips | trips:read | — |
| Events | events:read | — |
| Geofences | geofences:read | geofences:write |
| Remote config | config:read | config:write |
| Users | users:read | users:write (erase a user and their data) |
| Webhooks | webhooks:read | webhooks:write (create, change, test and delete webhooks) |
All read, All write and Clear set a column at once; nothing is chosen to start with, and a server key needs at least one scope. Write doesn’t include read. Scopes are fixed for the key’s life: to change them, issue a new key and revoke the old one. See Scopes.
The new key is shown with a warning (Copy this now.) and closes only with I’ve copied it.
For an SDK key the dialog shows the SDK setup lines; for a server key, a curl call to
/v1/token.
Until the project receives its first location, the page shows Waiting for your first location… above the cards, with Show setup code for each SDK. It checks every few seconds and counts gated locations too. When a location arrives it says First location received with Open Locations. It stops checking after 30 minutes (No location yet); Check again starts it again.
Each row shows the key’s name, prefix, status (Active or
Revoked), when it was last used and when it was Issued. Server keys
add their scopes and Calls · 7 days. Clicking the calls opens the key’s API calls dialog:
every /v1 call its sessions made over Last 7 days, Last 30 days or Last 90 days, split into succeeded
(2xx, 3xx), client errors (4xx, including calls outside the key’s scopes) and server errors
(5xx), per UTC day. It is up to a minute behind and kept 90 days; the token exchange itself is
not counted. The row menu has:
- Rename.
- Rotate…: replaces the key with a new one (a server key keeps its scopes). There’s no
overlap. For no downtime, issue a second key instead, move your backend or release your app
with it, then revoke the first. Type
rotateto confirm. - Revoke…: stops the key for good. No new session can start, and existing sessions stop
working within 2 seconds of the revocation reaching the project’s region, which is normally at
once (see Rotating and revoking keys). Type
revoketo confirm. Revoked keys fold away under Show n revoked keys.
A suspended project can’t issue or rotate keys; revoking and renaming still work.
After you issue an SDK key, a project with no app yet shows Next: add your app, with Add your app → to the Apps tab.
The project’s Android and iOS apps, each registered once by its package name or bundle ID with an optional nickname, up to 10 for each platform. From each app’s row you finish its Attestation (the signing certificates SHA-256 for Android, the App ID prefix and environment for iOS) and add it to the organisation’s SDK licence. Each is a chip with Add while it is missing. Edit and Remove say which changes ask attested devices to verify again. Members see the list without controls.
See Register your apps in the console for every field and chip, and Licensing for the licence.
Webhooks
Section titled “Webhooks”Beekon POSTs signed events to your HTTPS endpoints: geofence crossings, trips, device presence
and usage alerts.
Failed deliveries are retried for 24 hours. A project can have up to 10 endpoints.
See Webhooks for the payload and how to verify a signature. (The console says
endpoint; the Server API object is a webhook. They are the same thing.)
Add endpoint asks for:
- Endpoint URL: HTTPS on a public host name, port 443 or 1024–65535. Redirects are never followed.
- Events to send: All events (every type, including types Beekon adds later) or Only these events, which lists nine types: Entered a geofence, Left a geofence, Stayed in a geofence, Trip started, Trip ended, MAU threshold reached (50, 80, 100% of the cap), Trip stalled (its device went quiet), Device unreachable (Beekon lost contact) and Device back in touch.
The endpoint’s signing secret (whsec_…) is shown once, when it is added. Deliveries carry
Beekon-Signature: t=…,v1=…, an HMAC-SHA256 of t.body.
Event types and payloads
Section titled “Event types and payloads”Each choice under Events to send is one event type. Every delivery is a JSON body whose
events array holds these objects; the Payload link shows each one’s fields and examples.
| In the console | type | Sent when | Payload |
|---|---|---|---|
| Entered a geofence | geofence.enter | The server confirms a device entered a fence. | Geofence events |
| Left a geofence | geofence.exit | The server confirms a device left a fence, or, for a fence set to exit on unreachable, that a device inside it became unreachable. | Geofence events |
| Stayed in a geofence | geofence.dwell | A device stayed inside a fence for 5 minutes. | Geofence events |
| Trip started | trip.started | A device’s trip was first stored. | Trip events |
| Trip stalled | trip.stalled | An open trip’s device went quiet. | Trip events |
| Trip ended | trip.ended | A stored trip was closed. | Trip events |
| Device unreachable | device.unreachable | A device with a fence visit or a trip in progress stopped being reachable. | Device presence events |
| Device back in touch | device.reachable | That device was heard from again. | Device presence events |
| MAU threshold reached | billing.usage_threshold | The project’s MAU crossed 50%, 80% or 100% of your cap. | Usage threshold events |
| (Send test) | webhook.ping | You pressed Send test. Not a choice: it goes only to that endpoint. | Ping events |
A delivery of one Entered a geofence event:
{ "events": [ { "id": "019e9f61-1400-7000-8000-0000000000e1", "type": "geofence.enter", "detected_at": "2026-06-07T00:00:02.000Z", "device": {"install_id": "install-e1", "user_id": "acct_9931"}, "evidence": "track", "geofence": {"id": "019000f0-0000-7000-8000-0000000000f1"}, "location": { "accuracy_m": 12.5, "latitude": 12.9716, "longitude": 77.5946, "recorded_at": "2026-06-07T00:00:00.000Z" }, "occurred_at": "2026-06-07T00:00:00.000Z", "project_id": "019000b0-0000-7000-8000-0000000000b1" } ], "schema_version": 1}Every event has id (deduplicate on it: a retried event keeps its id), type, occurred_at
and project_id; the other fields depend on the type. A body carries 1 to 100 events, in no
particular order. Skip a type you don’t know and still answer 2xx. See
The delivery request for the headers.
Endpoint states
Section titled “Endpoint states”| State | What Beekon does |
|---|---|
| Active | Sends each event as it happens. |
| Paused | You chose Pause. Nothing is sent, and events that happen while it is paused are never sent to it later. Deliveries already queued wait up to 7 days from their event for Resume, then are given up. Tests still go. |
| Switched off | Beekon stopped sending after 20 failed attempts in a row. Events since then are not queued for it. Deliveries already queued wait up to 7 days from their event, then are given up. Any change you save, or Turn back on, turns it back on. |
| Turning back on | Sending resumes within a minute, starting with the deliveries on hold. |
The endpoint page
Section titled “The endpoint page”- Send test, Edit, Pause / Resume / Turn back on, Rotate secret and Delete…. After a rotation, deliveries are also signed with the previous secret, so your endpoint can switch; if the current secret leaked, choose to stop signing with it now. Beekon keeps two secrets at most.
- Send test sends one signed
webhook.pingand waits up to 10 seconds. Only a 2xx counts as delivered. A 401 or 403 usually means your endpoint rejected the signature; No response covers a host that doesn’t resolve, refuses the connection, fails TLS, redirects or is too slow. A test is not stored or retried, so it doesn’t appear in the delivery lists. - Delivery queue: Waiting to send, Sending now and Given up (kept 90 days). Send again puts the deliveries given up back in the queue.
- Recent deliveries: the 20 newest, with their state, event, device, tries, response and last activity.
Each delivery is in one of these states:
| State | Meaning |
|---|---|
| Waiting | Queued, not tried yet. |
| Sending | An attempt is open (up to 30 seconds). |
| Retrying | Failed, and tried again with growing gaps (at most 1 hour apart) for 24 hours from the first try. |
| On hold | The endpoint is paused or switched off. Waits up to 7 days from its event. |
| Delivered | Your endpoint answered 2xx. |
| Given up | Retried for 24 hours without a 2xx, or waited 7 days on hold. Send again queues it again. |