ROOK provides mechanisms for users to disconnect their data sources, and clients have the flexibility to create custom interfaces for this purpose. Here’s an overview of how users can disconnect a data source and how clients can implement this feature:
Revoking user authorization:
Users can disconnect a data source by revoking ROOK’s access to their health data.
This can be done using the /api/v1/user_id/{user_id}/data_sources/revoke_auth endpoint.
When this endpoint is used, all data sources associated with the specified user for the specific client are disconnected.
It's important to note that if a user's account is shared across multiple clients, revoking access for one client does not affect the user's connection with other clients.
Implementing a custom disconnect interface:
Clients are not limited to using ROOK’s default interface and are expected to build their own user interfaces for data source management.
The /authorizers endpoint can be used to retrieve data source details, including names, descriptions, logos, and authorization URLs.
Clients can use this information to create a custom interface within their application or web page, where users can manage their connected data sources.
The custom interface can include buttons or options for users to initiate the disconnection process.
When a user chooses to disconnect a data source, the application should use the /data_sources/revoke_auth endpoint.
API Endpoint for revoking access:
To revoke a user’s authorization, a POST request should be made to the /api/v1/user_id/{user_id}/data_sources/revoke_auth endpoint, including the user_id in the path and the specific data_source to be revoked in the request body.
The request must include basic authentication using the client’s client_uuid and secret_key.
The body of the request must include the data_source to revoke, which must be one of: "Garmin", "Oura", "Apple Health", "Health Connect", "Android", "Polar", "Fitbit", "Withings", or "Whoop".
Example request body
Upon successful revocation, ROOK will return a success message, indicating that the user’s authorization for the specified data source has been revoked.
Mobile-Based Data Sources:
For mobile-based data sources like Apple Health and Health Connect, authorization is handled directly on the user’s device.
If the user disconnects from within the mobile device settings, then data will no longer be available to ROOK.
The revoke_auth endpoint can also be used to disconnect mobile-based sources.
Important considerations:
Once a user has authorized ROOK to access their data, the connection remains active until explicitly revoked.
Clients should design their interfaces to clearly show users which data sources are currently connected and provide easy options to disconnect.
Data Source specific behavior: Some data sources allow users to manage application permissions directly within their own platforms (e.g., within the Garmin Connect app). If a user revokes permissions for a data source through its native interface, these changes may affect all applications and clients connected to that account through ROOK. This behavior is specific to the data source and should be considered when designing your user interface and communicating with users. Consult the documentation for each data source to understand its specific authorization management features.
For mobile-based data sources like Apple Health and Health Connect, authorization is handled directly on the user’s device. If the user disconnects from within the mobile device settings, then data will no longer be available to ROOK. The revoke_auth endpoint can also be used to disconnect mobile-based sources.
In summary, users can disconnect data sources through a custom interface built by the client, which uses ROOK's /data_sources/revoke_auth endpoint to revoke authorization. Clients can use the /authorizers endpoint to retrieve the information needed to build this interface and to present available data sources for connection and disconnection. This setup allows for flexible and user-friendly management of data source connections.