Skip to content

Scopes

A scope is one permission a server key carries, chosen when the key is issued. Each server endpoint requires exactly one scope; a key without it gets 403:

Terminal window
curl -s https://api.in1.getbeekon.com/v1/project -H "Authorization: Bearer $BEEKON_TOKEN"
# {"error":"insufficient scope"} when the key lacks project:read

POST /v1/token and the device-only endpoints below declare none. Give each backend service a key with only the scopes it needs.

There are 15. The list is closed: a key cannot carry any other value.

ScopeGrants
project:readGET /v1/project
devices:readGET /v1/devices and GET /v1/devices/{install_id}
devices:writePOST /v1/devices/{install_id}/commands: sending a device a command
locations:readGET /v1/locations, GET /v1/locations/feed
locations:writePOST /v1/ingest: uploading locations from your server in the SDK’s upload format. A server session receives none of the device-only members of the upload response (pending config revision, nearby geofences, device commands).
trips:readGET /v1/trips, GET /v1/trips/{trip_id} and GET /v1/trips/{trip_id}/points
geofences:readGET /v1/geofences and GET /v1/geofences/{fence_id}
geofences:writePOST /v1/geofences, PUT and DELETE /v1/geofences/{fence_id}
config:readGET /v1/config/document. Also GET /v1/config, the SDK’s fetch of the configuration devices receive.
config:writePUT /v1/config/document
events:readGET /v1/events
users:readGET /v1/users, GET /v1/users/{user_id} and GET /v1/users/{user_id}/devices
users:writeDELETE /v1/users/{user_id}: erasing a user’s data in the project
webhooks:readGET /v1/webhooks and GET /v1/webhooks/{webhook_id}. Also decides whether a write returns the full webhook object (see Webhooks).
webhooks:writePOST /v1/webhooks, PATCH and DELETE /v1/webhooks/{webhook_id}, rotate-secret and ping

Two endpoints exist only for devices and declare no scope: POST /v1/logs and GET /v1/device-state. A server session is refused on both, whatever scopes it holds. GET /v1/config is the SDK’s own config fetch and is not part of this API: it serves the configuration as devices receive it, and a server session with config:read that calls it gets that same form. From your server, read GET /v1/config/document.

  • Exactly. A route’s scope must appear, character for character, in the key’s set. There is no case folding and no trimming.
  • No wildcards. *, locations:* or all are not scopes and grant nothing.
  • No implication. write does not imply read, and no scope implies another. A key with only geofences:write can create a geofence but cannot list them; give it both if it needs both.
  • Fixed at issue. Rotating a key keeps its scopes. To change scopes, issue a new key and revoke the old one.
errorMeaningFix
insufficient scopeThe key lacks this route’s scope. The body never says which scope is missing, and no header does either.Check the route’s scope in this reference and issue a key that has it.
server credentials requiredThe token was minted from an SDK key (bkproj_…), not a server key.Mint the token from a bkserv_ key.
the location log is readable by server integrator credentials onlySame as above, on GET /v1/locations.Same.
the event log is readable by server integrator credentials onlySame as above, on GET /v1/events.Same.

The last two have their own wording. Match them as they are.

Every server endpoint checks a request in this fixed order, and answers with the first failure:

  1. Session: missing or invalid token, 401. If the server cannot read whether the token’s key is still active, it answers 503 credential status unavailable with Retry-After instead of guessing; retry after it.
  2. Key kind: not a server session, 403 (the key-kind bodies above).
  3. Scope: the key lacks the route’s scope, 403 insufficient scope.
  4. Validation: a bad parameter or body, 400 (or 413 too_large for an oversized remote-config document).
  5. Precondition: a stale If-Match on the remote-config document, 412.
  6. Lookup: an unknown id, 404 not found.
  7. Conflicts: 409, where an endpoint defines them.
  8. Our failures: 5xx.

Because scope is checked before validation, a key without the scope gets 403 even for a malformed request, and learns nothing about the request’s validity. Nothing is read from your project’s data before the scope check passes.

Before step 1, the path and method must match an endpoint. A path no endpoint serves answers 404 not found, and a method the path does not serve answers 405 method_not_allowed with an Allow header, with or without a token. See Errors.

The webhook endpoints add two platform answers and move one check. A 503 comes first, before the body is read, when the server runs no webhook service, and after validation and before the lookup when the service is briefly busy. A 429, when a rate limit is reached, comes after the lookup, and on create 409 webhook_limit_reached comes after the 429. A malformed webhook id answers 404 after the body’s shape is checked and before its member values are. See Webhooks.

Geofence writes check the plan’s vertex limit inside validation. 409 quota_vertices comes after the cheaper geometry checks and before the self-intersection and hole checks. On a PUT to an unknown id, 404 not found comes before it. See Geofences.

A server key issued before scopes existed holds exactly events:read, locations:read and locations:write, and so does any session minted from it. It reaches none of the other endpoints. To use them, issue a new key with the scopes you need.