Integration Guide

Data Consent Agency Integration

Services

Currently, the consent agency allows integration with 3 different services.

• Nightscout
• Suunto
• Polar

Webhooks

Enterprise agents can be provisioned with certain webhooks. These webhooks are triggered based on certain actions. These config variables can be found in config.js of enterprise agents. These webhook variables can be configured in the environment when the enterprise agent is deployed allowing any external system integration. Based on these webhooks other systems can perform necessary operations.

Config Variable	Description	Trigger
FETCH_CONSENT_PROPOGATION_URL	URL to propogate fetch type of consent	On fetch consent received
ACCESS_CONSENT_PROPOGATION_URL	URL to propogate access type of consent	On access consent received
REVOKE_CONSENT_PROPOGATION_URL	URL to propogate consent revocation	On revocation of consent received

Integration flow with Suunto & Polar Services

1. Provision agent and set up the enterprise agent webhook URLs.
2. When registering a Polar or Suunto service Data Consent Agency redirects the user to our front-end consent service with token & cred_def_id in query parameters.
   • token is an expiring (10min) access token for creating a "service".
   • cred_def_id is an id for the user to be identified in the Data Consent Agency.
3. The user accepts the consent and is redirected to Polar or Suunto to be authenticated, which then redirects the user to this repos OAuth2PolarRegisterUser or OAuth2SuuntoRegisterUser-function. It gives parameters specified in the previous step, and also an authorization code.
4. OAuth fetches Polar or Suunto API which creates and returns access token & user-id using the authorization code.
5. Access token & cred_def_id is sent to the Enterprise Agent to create a service which returns a service_id. This per-user service_id is saved to our database next to Polar or Suunto user id.

Now the user is created to our database, but the user doesn't have a credential to fetch data from the Agency. The Data Consent Agency has to do send us the credential asynchronously with the webhooks. Now the user has everything necessary to fetch data.

Integration flow with Nightscout

HAG Authentication is a requirement Nightscout integration. Nightscout access-token and api-url is required when registering a service in the agency. From agency, once HAG auth is done, nightscout service is registered and consent is issued the webhook is triggered and can be used to receive a credential and store it on the enterprise system side. Which can be used to fetch the data.

Fetching data

Solo-Enterprise-Agent (SEA) API is used to fetch data using the Enterprise Agent. See Solo-Enterprise-Agent (SEA) API documentation for reference.

Steps:

1. Authenticate Enterprise Agent using API request. Use response token in step-2 for authentication.
2. Retrieve the stored consent credential from the database.
3. Request data-access-token from the Enterprise Agent API request. Stored consent credential is used as an input and a JWT is returned in response which you use in step 4.
4. Use service_id & agency-endpoint from stored credential in step 2 for making a data-request to the Agency. See API documentation here.

HAG Authentication

A HAG service is required to issue delegated credentials, Contact TietoEVRY Blockchain CoE to get access to HAG Service. A guardian is issued a credential of their dependent that is used to auto-fill their information when issuing consent.