Skip to content

Developers

The Developers group holds what connects your app and your backend to the project. Owners and admins change it; members see it read-only.

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.

KindPrefixFor
SDK keysbkproj_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 keysbkserv_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:

ModuleReadWrite
Projectproject:read—
Devicesdevices:readdevices:write (send commands to devices)
Locationslocations:readlocations:write (send locations, POST /v1/ingest)
Tripstrips:read—
Eventsevents:read—
Geofencesgeofences:readgeofences:write
Remote configconfig:readconfig:write
Usersusers:readusers:write (erase a user and their data)
Webhookswebhooks:readwebhooks: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 rotate to 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 revoke to 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.

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.

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 consoletypeSent whenPayload
Entered a geofencegeofence.enterThe server confirms a device entered a fence.Geofence events
Left a geofencegeofence.exitThe 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 geofencegeofence.dwellA device stayed inside a fence for 5 minutes.Geofence events
Trip startedtrip.startedA device’s trip was first stored.Trip events
Trip stalledtrip.stalledAn open trip’s device went quiet.Trip events
Trip endedtrip.endedA stored trip was closed.Trip events
Device unreachabledevice.unreachableA device with a fence visit or a trip in progress stopped being reachable.Device presence events
Device back in touchdevice.reachableThat device was heard from again.Device presence events
MAU threshold reachedbilling.usage_thresholdThe project’s MAU crossed 50%, 80% or 100% of your cap.Usage threshold events
(Send test)webhook.pingYou 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.

StateWhat Beekon does
ActiveSends each event as it happens.
PausedYou 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 offBeekon 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 onSending resumes within a minute, starting with the deliveries on hold.
  • 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.ping and 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:

StateMeaning
WaitingQueued, not tried yet.
SendingAn attempt is open (up to 30 seconds).
RetryingFailed, and tried again with growing gaps (at most 1 hour apart) for 24 hours from the first try.
On holdThe endpoint is paused or switched off. Waits up to 7 days from its event.
DeliveredYour endpoint answered 2xx.
Given upRetried for 24 hours without a 2xx, or waited 7 days on hold. Send again queues it again.