Get started

Scopes

A scope is a permission your app asks the user for. Each one unlocks specific endpoints, and its description is shown to the user — word for word — on the Arkaayu consent screen.

All scopes#

Scope	What the user sees	Endpoints
`read:profile`	Your name and email address	`/api/me`, `/api/body-measurements`
`read:sleep`	Your sleep sessions, stages and sleep scores	`/api/sleep-data`
`read:steps`	Your daily steps, calories and active minutes	`/api/steps`
`read:heart_rate`	Your heart-rate readings and resting heart rate	`/api/heart-rate`, `/api/blood-pressure`
`read:spo2`	Your blood-oxygen (SpO2) readings	`/api/spo2`
`read:workouts`	Your recorded workouts and their heart-rate zones	`/api/workouts`
`read:ecg`	Your ECG recordings, including the recorded waveform	`/api/ecg`, `/api/ecg/{id}`

All scopes are read-only. The API cannot create, change or delete anything in a user's Arkaayu account.

Things to know#

read:profile covers body measurements#

Height and weight from /api/body-measurements come with read:profile, alongside the user's name and email. You don't need a separate scope for them.

read:heart_rate covers blood pressure#

Blood-pressure readings from /api/blood-pressure come with read:heart_rate. Keep this in mind when you describe what your app reads in your privacy policy.

read:ecg is the most sensitive scope#

ECG recordings include the full recorded waveform. During review we'll ask you to explain why your app needs ECG data and how you protect it. Apps that only need heart rate should not request read:ecg.

Requesting scopes#

Pass scopes as a space-separated list in the scope parameter of the authorize request (URL-encoded, so spaces become %20 or +):

HTTP

GET https://api.arkaayu.health/oauth/authorize?...&scope=read%3Aprofile%20read%3Asleep%20read%3Asteps

You can only request scopes that are enabled for your app in the console. Asking for anything else fails with invalid_scope.

The token response's scope field tells you what was granted. Use it to decide which features to switch on, rather than assuming you got everything you asked for.

Ask for the minimum#

Users are more likely to connect an app that asks for less, and reviewers check that each scope is genuinely needed by a feature in your app.

Request only the scopes your current features use. A sleep coach needs read:sleep, not read:ecg.
Prefer asking for more later, when the user turns on a feature that needs it, over asking for everything up front. Send the user through the authorize flow again with the extra scope.
Use the refresh scope parameter to give background jobs a narrower token (see Refreshing tokens).
Explain in your own UI, before the redirect, what you'll do with each kind of data.

Changing scopes after launch#

Once your app is live you can remove scopes from it at any time in the console. Adding a scope needs a new review — see Changes after going live.

Questions or something unclear? Write to developers@arkaayu.com.