# Permissions.

> https://meetkeely.com/developers/permissions · Updated 2026-11-06 · Keely, by Metrica Fit LLC

## The scopes

| Scope | On the consent page | What it gives |
|---|---|---|
| `profile` | Who you are | Your birth year, sex, height, weight, sleep goal and max heart rate, and your band: its name, firmware and last sync |
| `nights` | Mornings: Recovery and sleep | Each morning’s Recovery and what moved it, HRV, resting heart rate, breathing rate, skin temperature, sleep (stages, need, regularity) and your normals |
| `days` | Days: Load and stress | Each day’s Load and its target, time in heart-rate zones, steps, stress (day, night and moments) and naps |
| `workouts` | Workouts | Workouts and activities: the sport, times, Load, heart rate and zones |
| `journal` | Read your journal | Your journal and its tags, only while you share your journal in the Keely app (Journal › Assistants) |
| `journal:write` | Add to your journal | Add entries and tags when you ask it to, and delete what it added |

## What starts ticked

On the consent page, `nights`, `days` and `workouts` start ticked; `profile`, `journal` and `journal:write` start unticked, and `journal:write` can’t be ticked without `journal`. Ask only for what your app uses: the fewer the scopes, the more people allow.

The page shows only the scopes your app registered, and the person may untick any of them. So never assume you got what you asked for: read `scopes` from [`GET /v1/me`](https://meetkeely.com/developers/api/me#get-v1-me) after connecting, and handle `403 insufficient_scope` on every call, because the person can narrow a permission later and the change holds at your next request.

[`GET /v1/changes`](https://meetkeely.com/developers/api/changes) needs at least one scope, and lists only the kinds your scopes cover: nights with `nights`, days with `days`, workouts with `workouts`, the journal’s rows with `journal`. An app whose every permission the person turned off reads nothing, there as everywhere.

## The journal’s switch

The journal has a second gate, the person’s own. It reaches their account only while **Let assistants read and add to your journal** is on in the Keely app. Until then, every journal endpoint answers `409 journal_off`, whatever the scopes say.

## Not allowed is named, never empty

When parts of an answer need scopes you don’t have, those keys are left out and listed in `not_allowed`: a day read with `nights` alone comes with `"not_allowed": ["days", "workouts"]`. When the whole answer needs a scope you lack, the API answers `403 insufficient_scope`, with `scope`, the one needed, and `scopes`, the ones granted, so an empty table never reads as “nothing happened”.

```json 403 insufficient_scope
{
  "error": "insufficient_scope",
  "message": "This person hasn’t allowed your app to read their workouts.",
  "scope": "workouts",
  "scopes": ["nights", "days"]
}
```