# Scopes

> The 15 per-module permissions a server key carries, how they are matched (exactly, with no wildcards), the 403 bodies and the order of checks.

Source: https://docs.getbeekon.com/api/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`:

```sh
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.

## The scopes

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

| Scope             | Grants                                                                                                                                                                                                                                             |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project:read`    | [`GET /v1/project`](https://docs.getbeekon.com/api/project/)                                                                                                                                                                                                                 |
| `devices:read`    | [`GET /v1/devices`](https://docs.getbeekon.com/api/devices/) and `GET /v1/devices/{install_id}`                                                                                                                                                                              |
| `devices:write`   | [`POST /v1/devices/{install_id}/commands`](https://docs.getbeekon.com/api/devices/#send-a-command): sending a device a command                                                                                                                                               |
| `locations:read`  | [`GET /v1/locations`](https://docs.getbeekon.com/api/locations/), [`GET /v1/locations/feed`](https://docs.getbeekon.com/api/locations/#get-v1locationsfeed)                                                                                                                                            |
| `locations:write` | [`POST /v1/ingest`](https://docs.getbeekon.com/api/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`](https://docs.getbeekon.com/api/trips/), `GET /v1/trips/{trip_id}` and `GET /v1/trips/{trip_id}/points`                                                                                                                                                     |
| `geofences:read`  | [`GET /v1/geofences`](https://docs.getbeekon.com/api/geofences/) and `GET /v1/geofences/{fence_id}`                                                                                                                                                                          |
| `geofences:write` | [`POST /v1/geofences`](https://docs.getbeekon.com/api/geofences/), `PUT` and `DELETE /v1/geofences/{fence_id}`                                                                                                                                                               |
| `config:read`     | [`GET /v1/config/document`](https://docs.getbeekon.com/api/remote-config/). Also `GET /v1/config`, the SDK’s fetch of the configuration devices receive.                                                                                                                     |
| `config:write`    | [`PUT /v1/config/document`](https://docs.getbeekon.com/api/remote-config/)                                                                                                                                                                                                   |
| `events:read`     | [`GET /v1/events`](https://docs.getbeekon.com/api/events/)                                                                                                                                                                                                                   |
| `users:read`      | [`GET /v1/users`](https://docs.getbeekon.com/api/users/), `GET /v1/users/{user_id}` and `GET /v1/users/{user_id}/devices`                                                                                                                                                    |
| `users:write`     | [`DELETE /v1/users/{user_id}`](https://docs.getbeekon.com/api/users/#erase-a-user): erasing a user’s data in the project                                                                                                                                                     |
| `webhooks:read`   | [`GET /v1/webhooks`](https://docs.getbeekon.com/api/webhooks/) and `GET /v1/webhooks/{webhook_id}`. Also decides whether a write returns the full webhook object (see [Webhooks](https://docs.getbeekon.com/api/webhooks/#write-only-keys)).                                                           |
| `webhooks:write`  | [`POST /v1/webhooks`](https://docs.getbeekon.com/api/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`](https://docs.getbeekon.com/api/remote-config/).

## 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:*` 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.

A write can reveal what it creates

`webhooks:write` lets a key subscribe an endpoint of its choosing to your project’s events, so in practice it lets that key receive event data. Grant it with the same care as `events:read`.

## 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

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](https://docs.getbeekon.com/api/errors/#the-envelope).

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](https://docs.getbeekon.com/api/rate-limits/) 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](https://docs.getbeekon.com/api/webhooks/#errors).

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](https://docs.getbeekon.com/api/geofences/#limits).

## 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.
