Skip to content

Server API quickstart

This page takes you from a server key to a page of locations, then to a geofence event on your webhook, with curl and jq. You need a server key (bkserv_…) for your project with these scopes:

  • project:read and locations:read for the first part;
  • geofences:write, webhooks:write, locations:write and events:read for the second.
  1. Set your key and region host.

    Issue a server key on the console’s API keys page (owners and admins), choosing its scopes.

    The region is the second segment of your key: bkserv_in1_… lives on api.in1.getbeekon.com.

    Terminal window
    export BEEKON_SERVER_KEY='bkserv_in1_REPLACE_WITH_YOUR_SECRET'
    export BEEKON_API="https://api.$(echo "$BEEKON_SERVER_KEY" \
    | cut -d_ -f2).getbeekon.com"
  2. Exchange the key for a session token.

    Terminal window
    export BEEKON_TOKEN=$(curl -sf -X POST "$BEEKON_API/v1/token" \
    -H "Authorization: Bearer $BEEKON_SERVER_KEY" | jq -r .access_token)

    The response is {"access_token":"…","expires_in":3600}. The token lasts expires_in seconds; mint a new one when it expires or when a call returns 401. See Authentication.

  3. Check which project the key belongs to.

    Terminal window
    curl -s "$BEEKON_API/v1/project" -H "Authorization: Bearer $BEEKON_TOKEN"
    {
    "id": "0199b2c4-1f3a-7c11-9d2e-5a6b7c8d9e0f",
    "cell": "in1",
    "created_at": "2026-10-07T06:30:00.000Z",
    "name": "Fleet tracking",
    "status": "active"
    }

    A 403 {"error":"insufficient scope"} here means the key lacks project:read. Issue a new key with the scopes you need.

  4. Read a day of locations, one page at a time.

    Terminal window
    curl -s -G "$BEEKON_API/v1/locations" \
    -H "Authorization: Bearer $BEEKON_TOKEN" \
    --data-urlencode "from=2026-10-06T00:00:00Z" \
    --data-urlencode "to=2026-10-07T00:00:00Z" \
    --data-urlencode "limit=500"
    {
    "locations": [
    {
    "id": "0190…",
    "device": {"install_id": "2bed7f6c-…"},
    "is_mock": false,
    "latitude": 12.9716,
    "longitude": 77.5946,
    …
    }
    ],
    "next_cursor": "lc1_…",
    "retention_floor": null,
    "schema_version": 1
    }

    While next_cursor is a string, there is more. Repeat the same request with --data-urlencode "cursor=<next_cursor>" added, until next_cursor is null:

    Terminal window
    cursor=""
    while :; do
    page=$(curl -sf -G "$BEEKON_API/v1/locations" \
    -H "Authorization: Bearer $BEEKON_TOKEN" \
    --data-urlencode "from=2026-10-06T00:00:00Z" \
    --data-urlencode "to=2026-10-07T00:00:00Z" \
    --data-urlencode "limit=500" \
    --data-urlencode "cursor=$cursor") || break
    echo "$page" | jq -c '.locations[]
    | {install_id: .device.install_id, recorded_at, latitude, longitude}'
    cursor=$(echo "$page" | jq -r '.next_cursor // empty')
    [ -z "$cursor" ] && break
    done

Create a geofence and a webhook, upload two locations inside the fence from your server, and read the geofence.enter the server records. No app is needed: locations you send to POST /v1/ingest are checked against your geofences like the SDK’s.

  1. Create a geofence: a 200 m circle.

    Terminal window
    FENCE_ID=$(curl -sf -X POST "$BEEKON_API/v1/geofences" \
    -H "Authorization: Bearer $BEEKON_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "name": "Quickstart",
    "geometry": {
    "type": "circle",
    "center": {"latitude": 12.9716, "longitude": 77.5946},
    "radius_meters": 200
    },
    "notify_on_entry": true,
    "notify_on_exit": true
    }' | jq -r .geofence.id)
    echo "$FENCE_ID"
  2. Add a webhook for geofence events. endpoint_url must be a public HTTPS URL you control; for a first test, a request-inspection service works. The receiver code is on Webhooks.

    Terminal window
    curl -sf -X POST "$BEEKON_API/v1/webhooks" \
    -H "Authorization: Bearer $BEEKON_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "endpoint_url": "https://hooks.example.com/beekon",
    "event_types": ["geofence.enter", "geofence.exit"]
    }' | tee webhook.json

    The response’s secret (whsec_…) signs every delivery. It is shown only once, so keep webhook.json until you have stored it.

  3. Upload two locations inside the fence, 30 seconds apart. The second one confirms the enter (what produces a geofence event).

    Terminal window
    jq -n --arg a "$(uuidgen | tr A-Z a-z)" --arg b "$(uuidgen | tr A-Z a-z)" '{
    schema_version: 1,
    device: {install_id: "quickstart-device"},
    session_id: "quickstart",
    segments: [{locations: [
    {id: $a, timestamp: (now - 60 | todate), latitude: 12.9716, longitude: 77.5946,
    accuracy: 5, trigger: "interval", motion: "stationary", is_mock: false},
    {id: $b, timestamp: (now - 30 | todate), latitude: 12.9716, longitude: 77.5946,
    accuracy: 5, trigger: "interval", motion: "stationary", is_mock: false}
    ]}]
    }' > batch.json
    curl -s -o /dev/null -w '%{http_code}\n' -X POST "$BEEKON_API/v1/ingest" \
    -H "Authorization: Bearer $BEEKON_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @batch.json

    200 means the locations are stored. quickstart-device now appears in Devices and counts towards this month’s monthly active users like any device.

  4. Read the event.

    Terminal window
    curl -s -G "$BEEKON_API/v1/events" -H "Authorization: Bearer $BEEKON_TOKEN" \
    --data-urlencode "limit=500" \
    | jq '.events[] | select(.type == "geofence.enter")'
    {
    "id": "019e9f61-1400-7000-8000-0000000000e1",
    "type": "geofence.enter",
    "detected_at": "2026-11-01T06:40:12.000Z",
    "device": {"install_id": "quickstart-device", "session_id": "quickstart"},
    "evidence": "track",
    "geofence": {"id": "0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d"},
    "location": {
    "accuracy_m": 5,
    "latitude": 12.9716,
    "longitude": 77.5946,
    "recorded_at": "2026-11-01T06:40:10.000Z"
    },
    "occurred_at": "2026-11-01T06:40:10.000Z",
    "project_id": "019000b0-0000-7000-8000-0000000000b1"
    }

    The same event arrives at your webhook as a signed POST. In the in1 region it follows the upload within seconds; elsewhere it can take longer.

To clean up, delete the fence and the webhook:

Terminal window
curl -s -X DELETE "$BEEKON_API/v1/geofences/$FENCE_ID" \
-H "Authorization: Bearer $BEEKON_TOKEN"
curl -s -X DELETE "$BEEKON_API/v1/webhooks/$(jq -r .webhook.id webhook.json)" \
-H "Authorization: Bearer $BEEKON_TOKEN"