Participant Access Tokens
To guard against unauthorized use, MyDataHelps requires an access token. When using MyDataHelps Embeddables within your own application (outside of MyDataHelps), you will need to manage the participant’s access token yourself.
Tip
When using one of the MyDataHelps SDKs
within MyDataHelps (e.g., in a
Web View Step or a
MyDataHelps View), the access token is managed for you; you don’t need to do anything.
Participant Access Tokens vs Service Access Tokens
MyDataHelps has two different types of access tokens:
- Service access tokens are associated with a service account. Server-to-server applications use them with the REST API to access project resources from an administration standpoint.
- Participant access tokens are associated with a single participant. Client applications use them with the SDK to access data for a single participant.
Warning
Never use your service token in your client application. Use a participant token instead.
Since MyDataHelps Views, Embeddables, and Web View steps always take place within the context of a single participant, a participant-specific token limits access to just that participant’s data.
Access Token Data Flow
To maintain security of your data, it is imperative that you never include your service token or private key in your client application code. To request a participant token from your client application without using your service token, you will need to set up an authenticator to act as an intermediary.
Normally this authenticator will be part of your application layer, alongside whatever internal APIs your client app uses to get data and initiate actions. It could also be a stand-alone service. Either way, its purpose is to authenticate the user and then request a participant access token on their behalf.
Once you have the token, pass it to the SDK to initialize the participant’s session. To avoid connection interruptions, your client app must monitor for token expiration and request a new token (using the same process) before the old one expires.
Obtaining a Participant Access Token
To obtain a participant access token, your authenticator must first obtain a service token. See REST API Authentication for details. This lets the system verify that your app is authorized to request tokens on a participant’s behalf.
Once you have a service token, make a second request to the same token endpoint:
POST https://mydatahelps.org/identityserver/connect/token
Include the following fields:
| Field |
Meaning |
Value |
| scope |
The scope of access being requested. |
A space-separated list of scopes. See Scopes for a list of possible values. |
| grant_type |
The type of access being requested. |
delegated_participant |
| participant_id |
The participant’s globally-unique identifier. |
A participant identifier. |
| client_id |
Identifies the requesting application. |
RKStudio.DelegatedParticipant |
| client_secret |
A code associated with the requesting application. |
secret |
| token |
The service token. |
Your service token. |
Default values are used for client ID and client secret because the service token identifies your application and acts as a secret key.
If the token request is successful, the server’s response will include the following data:
| Field |
Meaning |
| access_token |
The alphanumeric access token. |
| expires_in |
When the token expires, expressed as a number of seconds from the date of the response. |
| token_type |
Bearer |
Note
To avoid connection interruptions, your client app must monitor the token’s expiration time and request a new token (using the same process) before the old one expires.
Scopes
A token can never access more than the associated participant would be able to, but you can use scopes to further limit what a token allows. As a best practice, only include the scopes you need for your desired use case.
api |
Full read/write access to all data for the associated participant. Avoid this in favor of finer-grained permissions whenever possible. |
AppleHealthActivitySummaries:read |
Read Apple Health activity summaries. |
AppleHealthWorkouts:read |
Read Apple Health workouts. |
CustomEvents:write |
Write custom events. |
DataCollectionSettings:read |
Read data collection settings. |
DeviceData:read |
Read device data. |
DeviceData:write |
Write device data. |
ExternalAccounts:connect |
Connect to external accounts. |
ExternalAccounts:read |
Read external accounts. |
ExternalAccounts:write |
Write to external accounts. |
FitbitDataSummary:read |
Read Fitbit data summary. |
FitbitDailySummaries:read |
Read Fitbit daily summaries. |
FitbitSleepLogs:read |
Read Fitbit sleep logs. |
Notifications:read |
Read notifications. |
Participant:read |
Read participant info. |
SurveyAnswers:read |
Read survey answers. |
SurveyResults:write |
Save survey results. |
SurveyTasks:read |
Read survey tasks. |
Initializing a Participant Session
Once you have a participant token, you must pass it to the SDK to initialize the participant session.
JavaScript SDK
In the JavaScript SDK, call:
MyDataHelps.setParticipantAccessToken(token)
iOS SDK
In the iOS SDK, you will need to initialize a ParticipantSession object. See MyDataHelpsKit Authentication for details.
Monitoring For Token Expiry
Participant tokens expire, so apps must refresh them to avoid service interruptions.
JavaScript SDK
In the JavaScript SDK, you can subscribe to the tokenWillExpire event to be notified of impending token expiration. See Events for details. Refresh the token (using the same process as the original request) and update it using:
MyDataHelps.setParticipantAccessToken(token)
iOS SDK
The iOS SDK doesn’t have an event for token expiration. Your app will need to keep track of the expires_in time returned by the token request. Refresh the token (using the same process as the original request) and create a new session. See MyDataHelpsKit Authentication for details.