Every API call must contain an access token to authorize access to your project’s data. This is sent in every API request. This article explains how you get an access token for your requests.
Contents
MyDataHelps has two different types of access tokens:
This guide deals with service access tokens. See Participant Access Tokens for information about participant-based access.
The basic steps for getting an service access token are:
These steps are described in more detail below.
Service accounts do not have passwords, but instead use a highly secure method for authenticating automated server-to-server applications called public key authentication. This mechanism is based on industry standards for data security, such as FHIR SMART Backend Services Authorization. In public key authentication, the server (MyDataHelps) uses the public key associated with your service account to confirm that your application has the correct private key.
When requesting an access token, your application will create a JSON Web Token Assertion (JWT Assertion) specifying information about the request.
The first part of this JWT Assertion is the header, which tells the server about the format of the assertion. Header fields include:
Field | Meaning | Value |
---|---|---|
alg | Algorithm | RS256 |
typ | Type | JWT |
Next are the claims, which contain information about the system making the request and the request itself. Claim fields include:
Field | Meaning | Value |
---|---|---|
iss | Issuer | Your service account name (e.g., MyDataHelps.1234.test). |
sub | Subject | Same as Issuer. |
aud | Audience | https://mydatahelps.org/identityserver/connect/token |
exp | Expiration | A timestamp (milliseconds since the Unix epoch) representing when the token expires. |
jti | Identifier | A unique identifier for each request. |
This claim is then signed using the private key that only your application knows.
The signed assertion is bundled in with a few other fields in a package called the JWT payload.
Field | Meaning | Value |
---|---|---|
scope | The scope of access being requested. | api |
grant_type | The type of access being requested. | client_credentials |
client_assertion_type | Defines the format of the assertion. | urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
client_assertion | The assertion itself. | Your signed assertion. |
Finally the JWT payload and header are sent to the MyDataHelps server. The server uses the public key associated with your service account to verify the validity of the signature, and thus the identity of your application.
Once you have a signed JWT, you can send it to the MyDataHelps server’s token request URL:
POST https://mydatahelps.org/identityserver/connect/token
application/x-www-form-urlencoded
content type. The payload must be posted as form parameters, not in the body data as JSON.
You can find sample code for making a token request in API Quickstart Apps. If the 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 |
If the request is unsuccessful, you will get an HTTP error code, typically a “400 - Bad Request” error. Here are some common reasons for a token request to fail:
After receiving the access token, you will need to include it in every API call. You can use the same token in multiple API calls until the token expires.
In your HTTP request, add a header named “Authorization” containing the value “Bearer YOUR_TOKEN”.