Participant Access Tokens

The participant access token is a unique access token associated with a specific participant on the MyDataHelps platform. It serves as a security measure to prevent unauthorized use of MyDataHelps resources and functions. This token allows the MyDataHelps SDK to identify and grant appropriate access to a particular participant’s data and activities within the platform.

When using the SDK within MyDataHelps (through Web View Steps or Views, this token is automatically managed by MyDataHelps. However, when integrating MyDataHelps outside MydataHelps (through your own client app or website using MyDataHelps Embeddables), you need to handle the management of participant access tokens on your own. This entails obtaining the token through the MyDataHelps REST API and ensuring it is used securely within your application to maintain security of participant data.

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 single participant, a participant-specific token limits access to just that participant’s data.

Access Token Data Flow for MyDataHelps Embeddables

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

Requesting a participant access token requires several steps:

1. Obtain a service access token.
2. Identify the participant.
3. Request a token for the participant.

Sample Code

You can find sample code illustrating how to get a participant access token in the MyDataHelps quickstart apps:

• Node.JS
• Python
• Java
• C# coming soon

Step 1: Obtain Service 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.

For an example of getting a service token, see one of the quickstart apps.

Step 2: Identify the Participant

Requesting a participant access token requires you to find the MyDataHelps participant ID corresponding to your application’s internal user.

The specific mapping will depend on how your application manages participants.

• If your application saves the MyDataHelps ID in its user data, the mapping is already done.
• If your application sets MyDataHelps participantIdentifier field (or another custom field) equal to the app’s user ID, you can utilize the MyDataHelps REST API (Get Participant) to query for a matching participant.

For an example of querying participants, see one of the quickstart apps.

Step 3: Request the Token

Once you have a service token and the participant ID, make another request to the same token endpoint to get the participant token.

For an example of getting a participant token, see one of the quickstart apps.

POST https://mydatahelps.org/identityserver/connect/token

Include the following fields:

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:

Managing the Participant Session

Once you have a participant token, you must pass it to the SDK to initialize the participant session. Participant tokens expire, so apps must refresh them to avoid service interruptions.

JavaScript SDK

In the JavaScript SDK, set up the session with:

MyDataHelps.setParticipantAccessToken(token)

You can subscribe to the tokenWillExpire event to be notified of impending token expiration. See Events for details. When the token expires, request a new token (using the same process as the original request) and call setParticipantAccessToken again to update the session.

iOS SDK

In the iOS SDK, you will need to initialize a ParticipantSession object.

Your app will need to keep track of the expires_in time returned by the token request. When the token expires, request a new token (using the same process as the original request) and create a new session.

See MyDataHelpsKit Authentication for details.

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.