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.
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.
Contents
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.
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. This token is then returned to the client app and passed along to the SDK to initialize a participant session.
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. | api |
| 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 |
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.
Refreshing Access Tokens
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.
In the JavaScript SDK, you can subscribe to the
tokenWillExpire event to know when the token is about to expire.
