Skip to content

Data sharing & access

Two independent things gate whether the Research API returns a piece of a user's data to you:

  1. Groups: is that user currently a member of a group your API key is linked to? This determines who you can attempt to query at all.
  2. Sharing: has that user actively shared their data with you, and for how long and at what level? This determines what, if anything, actually comes back.

Both are managed in the NOWATCH dashboard, and a user is always in full control of what gets shared and with whom.

API keys are scoped to groups, not users

An API key is never linked to individual users directly. Instead, it's linked to one or more groups, and can reach the union of every linked group's current members. Groups exist so a key doesn't need to be reissued every time who it can reach changes:

  • Your own data: create a group containing just your own account and link a key to it. No sharing step is needed for this: you always have full access to your own data.
  • One other person's data: once they've shared with you (see below), add them to a group and link a key to it.
  • A cohort: add every participant who has shared with you to a single group, and link one key to it. Adding or removing a member immediately changes what every key linked to that group can reach, with no new key required.

A key can be linked to more than one group at a time. If a group is removed from a key, the key isn't deleted; it just loses that group's members, and is only disabled once none of its linked groups remain.

Create and manage groups and keys in the NOWATCH dashboard

Group membership only determines which user_ids a key is allowed to attempt to query; see Finding which user_ids you can access. It does not by itself return any data. That's governed entirely by sharing, below.

Requesting access

To gain access to a user's data, that user shares their dashboard with your account:

  1. From Home or Your Dashboard, they click the person icon in the top right.
  2. They enter your account's email address.
  3. They choose an access date range and an access level (see below).
  4. They click Share. You can also initiate this from your side: open the sharing area of the dashboard, enter the user's email, and click Request. The user still has to approve the request before any data becomes available.

Manage sharing in the NOWATCH dashboard

When a user accepts, the share becomes active. Their data becomes readable through the Research API for any key linked to a group they belong to (add them to one if they aren't already). Access can be edited or revoked at any time by adjusting the end date, access level, or export permission, and this immediately changes what the Research API can retrieve.

What a share controls

Each share is scoped along several independent axes. A data point is returned only if it satisfies all of them:

Control Effect on the Research API
Access level Determines which categories of data are included. Options are: Full access (everything), Limited access (everything except Check-Ins and Feelings), Timeline only (Reactivity Monitor, Heart Rate, Steps), Overview only (Stress, Intense Activity, Resting Heart Rate, Sleep, Heart Rate Variability, Temperature), or Custom data (a user-chosen subset of the above). Only the shared categories are returned.
Date window The share defines a date range for the shared data. Requests are automatically limited to that window; data outside it is not returned.
Weekdays only If enabled, weekend (Saturday/Sunday) data is excluded.
Data export The share must explicitly permit data export for the data to be retrievable through the Research API. Sharing a dashboard for viewing does not, on its own, permit export.

One more prerequisite: the user must have chosen Share data (rather than Don't share data) in their own account settings. If they haven't, their data won't appear on any dashboard, including yours, regardless of what a share specifies.

Sharing is unidirectional

If a user shares their dashboard with you, and they're a member of a group linked to your key, you can read their data. They cannot read yours unless you also share with them, and your account is in turn added to a group linked to their own key.

In short: a piece of data is visible to the Research API only if it would show up on the user's own dashboard, they've shared it with you, and they're currently reachable through one of your key's linked groups. Anything they haven't shared, don't have visibility into themselves, or that falls outside your key's linked groups, stays out of reach.