Skip to content

Changelog

Every change to the /v1 server API is listed here, newest first. Within /v1 changes are additive (see Versioning); anything that could still affect an existing integration is marked Check your integration.

All four SDKs move to 0.6.0: Android (io.github.beekonlabs:beekon), iOS (BeekonKit from beekon-ios-binary), Flutter (beekon_flutter) and React Native (@wayq/beekon-rn). Flutter and React Native wrap the native 0.6.0 SDKs and have no API change. There are no breaking changes and no change to the local store. Install snippets are on Quickstart.

Presence and geofencing (Cloud mode)

  • A phone at rest says so. When the SDK pauses on its own stationary detection, it tells the server the device is resting; moving again ends that. On iOS the SDK pauses only with Always authorisation, so with When In Use it declares nothing. Under tracking.when_stationary pause (the default) the server reads a 0.6.0 install by what it says: resting until the project’s rest limit, moving otherwise. See device presence.
  • Sampling near a fence. A moving device near a fence’s boundary records a location every 5 seconds or 10 metres for at most 120 seconds per approach, uploads at once when it crosses a fence or comes close, and records one fresh location to judge an OS crossing (Android: any crossing without a location, also while paused; iOS: a polygon fence’s crossing). See Near a fence.

Device integrity (Cloud mode)

  • The SDK attests in the background, at most once a day: Android with hardware key attestation (no Google setup), iOS with App Attest (add the App Attest capability). Locations from an attested install are stored with trust_tier: attested. Register your apps in the console’s Apps tab first. See Device integrity.
  • Uploads refused with 403 attestation_required (when the project requires attestation) keep their locations on the device and send them once it verifies.
  • The install id moves out of backup and device transfer (Android: the no-backup files directory; iOS: a this-device-only Keychain item). A phone restored from a backup starts as a new install. Android apps need no backup-rules changes.

Push token handling

  • Android adds Beekon.setPushToken(token) and Beekon.handlePushMessage(data). iOS adds Beekon.shared.startMonitoringLocationPushes(appGroup:) and the BeekonLocationPush package product for a Location Push Service Extension. They let Beekon Cloud check on a silent device with one push before it reports the device unreachable (the push probe).
  • The probe is still switched off in Beekon Cloud, so these calls change nothing yet: no token is sent while the probe is off. Wire them now and the app answers once the probe is turned on for your project. Flutter and React Native have no API for this yet: call the native methods from the host app.
  • The token is never logged. A token copied by a backup restore, or one the push service no longer accepts, is dropped by the server when the push service reports it gone.

Android, in your FirebaseMessagingService (Beekon takes no Firebase dependency):

class AppMessagingService : FirebaseMessagingService() {
override fun onNewToken(token: String) {
Beekon.setPushToken(token)
}
override fun onMessageReceived(message: RemoteMessage) {
// Beekon's probe is a data message; it shows nothing to the user.
if (Beekon.handlePushMessage(message.data)) return
// Not Beekon's: handle your own message.
}
}
// Once at launch, after Beekon.configure(...) with BeekonConfig.cloud(...) in Application.onCreate
// (a probe can start the process):
FirebaseMessaging.getInstance().token.addOnSuccessListener { Beekon.setPushToken(it) }

handlePushMessage returns true for Beekon’s message and false for any other. It returns at once and never throws; the answer runs as a WorkManager job. A force-stopped app receives no FCM message, so it can’t answer.

iOS needs the com.apple.developer.location.push entitlement (Apple grants it on request) on the app and the extension, the same App Group on both, and Always location authorisation:

// In the app, at every launch, after configure with the cloud arm:
await Beekon.shared.startMonitoringLocationPushes(appGroup: "group.com.example.app")
// In the Location Push Service Extension target, which links BeekonLocationPush:
import BeekonLocationPush
import CoreLocation
final class LocationPushService: NSObject, CLLocationPushServiceExtension {
private let beekon = BeekonLocationPush(appGroup: "group.com.example.app")
func didReceiveLocationPushPayload(
_ payload: [String: Any], completion: @escaping () -> Void
) {
if beekon.handle(payload, completion: completion) { return }
completion() // Not Beekon's: handle your own location push first.
}
func serviceExtensionWillTerminate() {
beekon.serviceExtensionWillTerminate()
}
}

Licensing (Cloud mode)

  • The delivered licence key is cached on the device for 30 days after the last successful config fetch. A delivered key that fails verification never replaces a cached one that verifies, and a revoked licence ages out after the 30 days. See In Cloud mode.

Fixes

  • The background-location permission rationale no longer says tracking is foreground-only. Tracking started in the foreground keeps running in the background with a while-in-use grant; the background grant adds restart after the app is killed or the device reboots, geofences and the stationary pause.
  • Android: near a fence, a parked device whose locations stay within 10 metres no longer keeps the 5-second request running past the 120-second limit.

Check your integration

  • Devices that go silent while moving are reported sooner. With 0.6.0 a device that is not resting gets the moving deadline: twice its upload interval plus 120 seconds, with the interval counted as at least 900 seconds on Android and 60 seconds on iOS (1920 seconds on Android and 720 seconds on iOS with the default 300-second interval), instead of the 12-hour rest limit. Expect more device.unreachable events with presence.reason silent_while_moving, and sooner, as your users update.
  • Trips of a resting device end on the declaration. A trip ends with end_reason stop when a 0.6.0 device declares rest, instead of stalling after 10 minutes without contact.
  • More trust_tier: attested locations. The tier is a label and changes nothing unless you turn on Require attestation.

New endpoint

  • GET /v1/locations/feed (locations:read): every location of the project once, in the order it arrived, from an lf1_ cursor that is never null. Locations a device uploads late appear after your cursor instead of inside a window you already read. Positions are kept for 7 days.

Presence, trip closure and geofence evidence (2026-11-01)

Section titled “Presence, trip closure and geofence evidence (2026-11-01)”

New event types

New members and values

  • Geofence events: detected_at and evidence (track, interpolated, corroborated, unreachable) on every event, occurred_after on unreachable exits, and late: true on visits rebuilt from late locations. See Geofence events.
  • Trip events: detected_at on all three types.
  • The trip object: status stalled, and end_reason tracking_stopped (the app called stop()) and silence (no contact for trips.finality_timeout_seconds).
  • The geofence object: pass_through (off, on) and on_unreachable (none, exit), always present on output and optional on POST and PUT.
  • Remote config: trips.silence_timeout_seconds (0, or 60–86400; default the effective max_gap_seconds), trips.finality_timeout_seconds (3600–604800, default 86400), and a presence section with rest_limit_seconds (3600–604800, default 43200). Like trips and filters, presence is kept when a PUT leaves it out.

Changed behaviour

  • Geofence crossings confirm sooner. A moving device confirms an enter on its first location clearly inside, and an exit on its first location clearly outside by twice the usual margin. Otherwise a second location at least 10 seconds after the first confirms it; the 30-second rule is gone. A crossing the SDK reports confirms at once on an admitted location in the same upload that does not contradict it. See What produces a geofence event.
  • Late locations can produce events. A complete visit in locations that arrive late (up to 72 hours behind) is sent as an enter and an exit with late: true.
  • stop() closes the trip. The SDK’s stop report (SDK 0.5.0 and later) closes the open trip with tracking_stopped: within seconds in the in1 region; in other regions, when the region next handles traffic. Before, the trip stayed open until the device next tracked, then closed with session_change.
  • Silent devices’ trips close. No contact for finality_timeout_seconds closes an open or stalled trip with silence.
  • Dwell respects presence. A dwell is not sent for a device that became unreachable before the dwell time was reached, or while its visit is unverified.

Check your integration

  • Endpoints with event_types: null receive the three new types. null means every type. Skip types you don’t know, or give the endpoint an explicit list of the types it handles.
  • A geofence event’s location can be absent. An exit with evidence: unreachable has no location; its time is the window from occurred_after to occurred_at. You only get these from fences you set to on_unreachable: exit. Don’t read location unconditionally.
  • trip.ended can fire without a new location. A tracking_stopped or silence close comes from the device’s stop report or from the server’s clock, not from a location, so ended_at (the last location’s time) can be hours before detected_at.
  • A trip’s status can be stalled. Code that reads any status other than open as closed must check for closed. A stalled trip can still return to open and grow.
  • Ignore a trip.stalled that arrives after its trip’s trip.ended, and between two trip.stalled events for one trip, keep the higher trip.revision. A trip’s revision now also rises on each stall and each return to open.
  • session_change is rarer. Trips that used to close with session_change at the next start() now close with tracking_stopped when the app calls stop().
  • More geofence events, earlier. Events can fire on one location. A fast drive-through of a small fence that used to send nothing now sends an enter and an exit when one moving location lands clearly inside, or, with no location inside, when the fence has pass_through: on.
  • A late event is history. Its occurred_at can be hours or days old, and it never says where the device is now. Don’t update a device’s current state from it.
  • Treat an evidence value you don’t know as “decided by the server, evidence unknown”.
  • A geofence PUT resets the policies you leave out. A PUT built from a geofence read before this release has no pass_through or on_unreachable, and resets both to off and none. Read the fence again before you replace it.
  • features.presence_probe belongs to the server. A config PUT that carries it is 400 invalid_config: features.presence_probe. GET /v1/config/document never shows it, so a read-modify-write of the document is safe; don’t copy features from what devices receive. The flag belongs to the optional push probe, which arrives switched off with this release. Turning it on needs the region to enable it, push credentials and an SDK release after 0.5.0. Until then no event carries presence.probe_unanswered.
  • Server-key uploads don’t count as contact. A device whose locations reach Beekon only through server-key uploads to POST /v1/ingest never produces presence events, and its trips never stall or close with silence. The SDK’s own uploads to the same endpoint are contact.
  • Know the limits. A dead or force-stopped phone is reported unreachable, never located; an iOS app the user force-quits may leave the decision to presence; and a faked location on a rooted or jailbroken device is judged like any other. See known limits.
  • The webhook pages now say endpoint, the console’s word, for what they called a subscription. The API object is still webhook, and deliveries still carry Beekon-Subscription.
  • Errors lists 503 credential status unavailable, which any authenticated endpoint can answer when the server cannot read whether the token’s key is still active. It carries Retry-After; retry after it.
  • Authentication gives the real bound for a revoked key’s tokens: at most 2 seconds after the revocation reaches the region.

New event types

  • trip.started when a trip is first stored, and trip.ended when it is first closed. Each carries the trip object as it was then. Webhook event_types accept both. A trip that was already open when trip events were switched on in its region sends a trip.ended without a trip.started.

Check your integration

  • Endpoints with event_types: null receive trip events. null means every type. Skip types you don’t know, as always.
  • Billing usage events now appear in GET /v1/events. billing.usage_threshold events were meant to be in the feed, and these pages said they were, but the feed did not return them. It does now. Usage events produced before this change appear once, at the point in the feed where this change landed, so expect a few older occurred_at values there. Deduplicate on id as usual.

Check your integration

  • Ingest refuses bad locations. On POST /v1/ingest, a location or geofence event without a timestamp, a latitude outside −90…90, a longitude outside −180…180, a negative accuracy, or a NUL character in device.install_id or session_id is now 400 invalid batch for the whole batch. A location with no timestamp used to be dropped under 200.
  • A NUL character in the locations install_id filter is 400 invalid_install_id.
  • A whitespace-only geofence name is 400 invalid_name.
  • Every 429 and 503 carries Retry-After.
  • Keys take effect at once. A newly issued or revoked key works, or stops, straight away. Still retry a 401 unknown project key for up to 60 seconds before you alert. See Authentication.

Documentation

  • Corrections across the API pages and openapi.yaml: every operation now declares 429 and 503, GET /v1/events reads the first of a repeated limit, and the two ingest 503s a retry cannot fix are named.

Check your integration

  • Revoked keys end their tokens. A session token minted from a server key stops working at most 2 seconds after the key’s revocation or rotation reaches the region (401 invalid session token). The Authentication page said such tokens stayed valid until they expired; that was wrong. Move to the new key before you revoke the old one.
  • Device command bodies are capped at 16 KiB. A larger body to POST /v1/devices/{install_id}/commands is 400 invalid_body. A real command is a few hundred bytes, so no valid request is affected.
  • Geofence vertex limit checked first. A geometry over your plan’s vertex limit is now 409 quota_vertices even when it also crosses itself (it was 400 self_intersection). The cheaper geometry checks still answer 400 first, and a PUT to an unknown id is still 404 not found. See Limits.

Documentation

  • Users: GET /v1/users, GET /v1/users/{user_id}, GET /v1/users/{user_id}/devices and DELETE /v1/users/{user_id}, the users:read and users:write scopes, the device object’s user_id member and the GET /v1/devices user_id filter. These shipped with the full server-key surface and were missing from these pages (openapi.yaml already had them).
  • Ingest: extras over 4 KiB is 400 invalid batch; the 413 extras bound is the extras’ size times the batch’s locations, over 256 KiB.

New endpoints

  • GET /v1/project: the project a key belongs to.
  • Devices: GET /v1/devices, GET /v1/devices/{install_id}, and POST /v1/devices/{install_id}/commands (flush, upload_logs).
  • Users: GET /v1/users, GET /v1/users/{user_id}, GET /v1/users/{user_id}/devices and DELETE /v1/users/{user_id}, with the users:read and users:write scopes.
  • Trips: GET /v1/trips, GET /v1/trips/{trip_id} and GET /v1/trips/{trip_id}/points, from server-side trip detection.
  • Geofences: list, create, read, replace and delete.
  • Remote config: GET and PUT /v1/config/document, including the trips and filters sections, with ETag / If-Match.
  • Webhook endpoints: list, create, read, PATCH, delete, rotate-secret (with expire_previous) and ping.

New members and values

  • Locations carry a mode, always present, and GET /v1/locations takes a mode filter (400 invalid_mode).
  • A new event type, webhook.ping, sent only to an endpoint you ping. Consumers that skip unknown types already handle it.
  • New error statuses on the new endpoints: 409, 412 precondition_failed, 413 too_large and 503 unavailable, retry. See Errors.
  • A path under /v1 that no endpoint serves now answers 404 with the JSON body {"error":"not found"}, and a method a path does not serve answers 405 with {"error":"method_not_allowed"} and an Allow header. Both used to be plain text.

Check your integration

  • Scopes. Every server endpoint now requires a scope. Keys issued before scopes keep exactly what they could reach before (events:read, locations:read, locations:write) and reach none of the new endpoints. Issue a new key with the scopes you need. A key without a route’s scope gets 403 insufficient scope.
  • Webhook secret rotation. A rotation now keeps the previous secret until the next rotation, and deliveries are signed with both. The old secret can be retired once real-event deliveries verify with the new one; see Secret rotation.
  • Disabled webhook endpoints. Deliveries queued for an endpoint that is disabled (by you, or by auto-disable) now wait up to 7 days after the event was produced. Older ones are given up and are not sent automatically when you set it active again. Catch up on GET /v1/events.
  • GET /v1/locations: stored locations for a window, with device, user and admission filters, lc1_ cursors and retention.
  • bkserv_ server keys, exchanged for a session token at POST /v1/token, and server-side uploads to POST /v1/ingest.