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:
curl -s https://api.in1.getbeekon.com/v1/project -H "Authorization: Bearer $BEEKON_TOKEN"# {"error":"insufficient scope"} when the key lacks project:readPOST /v1/token and the device-only endpoints below declare none. Give each backend service a key
with only the scopes it needs.
The scopes
Section titled “The scopes”There are 15. The list is closed: a key cannot carry any other value.
| Scope | Grants |
|---|---|
project:read | GET /v1/project |
devices:read | GET /v1/devices and GET /v1/devices/{install_id} |
devices:write | POST /v1/devices/{install_id}/commands: sending a device a command |
locations:read | GET /v1/locations, GET /v1/locations/feed |
locations:write | POST /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:read | GET /v1/trips, GET /v1/trips/{trip_id} and GET /v1/trips/{trip_id}/points |
geofences:read | GET /v1/geofences and GET /v1/geofences/{fence_id} |
geofences:write | POST /v1/geofences, PUT and DELETE /v1/geofences/{fence_id} |
config:read | GET /v1/config/document. Also GET /v1/config, the SDK’s fetch of the configuration devices receive. |
config:write | PUT /v1/config/document |
events:read | GET /v1/events |
users:read | GET /v1/users, GET /v1/users/{user_id} and GET /v1/users/{user_id}/devices |
users:write | DELETE /v1/users/{user_id}: erasing a user’s data in the project |
webhooks:read | GET /v1/webhooks and GET /v1/webhooks/{webhook_id}. Also decides whether a write returns the full webhook object (see Webhooks). |
webhooks:write | POST /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.
How scopes are matched
Section titled “How scopes are matched”- 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:*orallare not scopes and grant nothing. - No implication.
writedoes not implyread, and no scope implies another. A key with onlygeofences:writecan 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.
Refusals: the 403 bodies
Section titled “Refusals: the 403 bodies”error | Meaning | Fix |
|---|---|---|
insufficient scope | The 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 required | The 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 only | Same as above, on GET /v1/locations. | Same. |
the event log is readable by server integrator credentials only | Same as above, on GET /v1/events. | Same. |
The last two have their own wording. Match them as they are.
The order of checks
Section titled “The order of checks”Every server endpoint checks a request in this fixed order, and answers with the first failure:
- Session: missing or invalid token,
401. If the server cannot read whether the token’s key is still active, it answers503 credential status unavailablewithRetry-Afterinstead of guessing; retry after it. - Key kind: not a server session,
403(the key-kind bodies above). - Scope: the key lacks the route’s scope,
403 insufficient scope. - Validation: a bad parameter or body,
400(or413 too_largefor an oversized remote-config document). - Precondition: a stale
If-Matchon the remote-config document,412. - Lookup: an unknown id,
404 not found. - Conflicts:
409, where an endpoint defines them. - 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.
Older server keys
Section titled “Older server keys”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.