Data Authorization

Data Authorization

Authorization is the first step to accessing health data through ROOK. Depending on the type of data source, the authorization process varies. This guide explains the two types of authorizations: API-Based Data Sources and Mobile-Based Data Sources, and provides instructions for integrating both.

---

Overview of Data Authorization

ROOK supports two types of data sources:

1. API-Based Data Sources: Platforms such as Fitbit, Garmin, and Oura, where users authorize access via the data source's authorization page.
2. Mobile-Based Data Sources: Platforms such as Apple Health and Health Connect, where users grant access directly on their mobile devices.

Both types of authorization are essential to enable data extraction and delivery through ROOK.

---

API-Based Data Sources

For API-based data sources, users authorize ROOK to access their health data via a browser or in-app web view. The setup can be achieved through the following methods:

1. ROOK Connections Page (Sandbox Testing)

ROOK provides a pre-made ROOK Connections Page for sandbox testing:

• Purpose: Simplifies sandbox testing by offering a ready-to-use webpage for user authorization.
• Configuration: The data sources displayed on the Connections Page can be managed through the ROOK Portal.
• Usage: The Connections Page can be embedded in a web view using this URL format:

  https://connections.rook-connect.com/client_uuid/{client_uuid}/user_id/{user_id}

note

The ROOK Connections Page is intended for sandbox testing only. For production, a custom page must be created using the /authorizers endpoint. See the API Reference for details.

---

2. Custom Connections Page (Production)

For production environments, a custom Connections Page or app view must be built to handle user authorizations.

Steps to Build a Custom Connections Page

1. Use the /authorizers Endpoint: Retrieve data source details, including names, descriptions, logos, and authorization URLs.

   Request:

   GET /api/v1/client_uuid/{client_uuid}/user_id/{user_id}/data_sources/authorizers
   Authorization: Basic {Base64Encoded(client_uuid:secret_key)}

   Parameters:

   • client_uuid: The unique client identifier from ROOK.
   • user_id: A unique identifier for the user (1–50 characters).
   • redirect_url (Optional): A custom URL for redirecting users after authorization.

   Example Response:

   {
     "client_name": "demoClientName",
     "theme": "Dark",
     "data_sources": [
       {
         "name": "Fitbit",
         "description": "Fitbit is part of Google. Together we can make health and well-being more accessible.",
         "image": "https://static.img/fitbit.png",
         "connected": false,
         "authorization_url": "https://www.fitbit.com/oauth2/authorize?response_type=code&client_id=..."
       }
     ]
   }
   info

   For full details, refer to the API Reference.

2. Design the Interface: Create a web page or app view with buttons for each data source. Each button should link to the authorization_url provided by the /authorizers endpoint.

   Connections View Example:

3. Handle Redirection: After authorization, users are redirected to the callback URL specified in the request. More information on setting up a callback URL can be found in the Callback URL Setup section.

note

Certain data sources, such as Whoop and Dexcom, require additional integration steps. Contact ROOK Support for assistance.

---

Mobile-Based Data Sources

For mobile-based data sources, such as Apple Health and Health Connect, authorization occurs directly on the user’s device.

Authorization Process

1. SDKs for Custom Apps: ROOK SDKs can be used to invoke authorization popups that allow users to grant access to their health data.

   • Platforms supported: iOS (Apple Health) and Android (Health Connect).
   • Integration: The SDK can be added to an app, and authorization functions can be triggered. Details are available in the SDK Documentation.

2. ROOK Extraction App: For clients without mobile development resources, the ROOK Extraction App provides a production-ready solution.

   • Users scan a QR code generated via the ROOK API to initialize authorization.
   • The app manages data extraction and authorization popups automatically.

More information can be found in the ROOK Extraction App section.

---

Revoke User Authorization

To revoke ROOK access to a user’s health data, the Revoke endpoint can be used:

Request:

POST /api/v1/user_id/{user_id}/data_sources/revoke_auth
Authorization: Basic {Base64Encoded(client_uuid:secret_key)}

note

Revoking access disconnects the user from all associated data sources for the specified client. If the same account is shared across clients, other clients retain access.

---

Key Notes

1. Authorization is One-Time: Once authorized, the connection remains active unless explicitly revoked or user permissions change.

2. API-Based vs. Mobile-Based:

   • API-based sources require a Connections Page or the /authorizers endpoint.
   • Mobile-based sources handle authorization natively via SDKs or the ROOK Extraction App.

3. Pre-Existing Data Access: Following authorization, ROOK retrieves up to 7 days of historical data, enabling immediate insights.

4. Production Readiness: The sandbox Connections Page should not be used in production. Custom pages or app views must be built for production environments.

---