Participant Access Tokens

To guard against unauthorized use, MyDataHelps requires an access token. 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. However, when using a MyDataHelps Embeddable to access the system outside of MyDataHelps, you will need to manage the participant’s access token yourself.

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.

Since MyDataHelps Views, Embeddables, and Web View steps always take place within the context of a particular user, 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 app 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 (in seconds).
token_type Bearer