There are two scenarios in which authentication is required in SMART Genomics: (1) when an app accesses an account's data; and (2) when an account accesses external records of the container (server). SMART Genomics uses OAuth2.0 for both authentication processes.

Table of Contents


All third-side clients must register against a SMART Genomics container before accessing data from that container. There are two steps that are necessary in order for a third party to access data using SMART Genomics' version of OAuth2: (1) Obtain an access token; and (2) use the access token to access data. One must obtain an access token using this work flow (with redirectable url). To use an access token in a request, use the HTTP Authorization header as below:

Authorization: bearer {access_token}

Triggering Web App

When a web-based application is launched within a SMART Genomics container (server), the app will be hit with the following HTTP request:


GET {launch_uri_registered}


api_base = {base_url_of_the_api_server},
launch_with = {resource_type}/{id_of_the_resource} //optional

The parameter launch_with indicates the resource that the user launches with the app. Possible values for {resource_type} are patientsequencinganalysis, and sequencinglab.


Different permissions that are required to access different resources are specified on this page. To inform the user of the scope of your access, set scope to be a space-delimited list of permissions when requesting authorization code from the user.
Below is an example scope specifying the right to read the user's sequence and patient resources in the user's account:

scope = read:sequence read:patient


permission in the OAuth2.0 flow of SMART Genomics API is formatted as follows:


with resource being one of FHIR resources or file. An exception to this rule is that file can also have permission as follows:


Here is a list of possible operations with a brief explanation:

  • read - The right to access existing resources
  • write - The right to modify content of existing resources
  • delete - The right to delete resources
  • create - The right to create resources
  • admin - The right covering all of the above

Obtaining access token

Get authorization code* by redirecting the user to an authorization page, specifying your client id and scope**.

1. Use the HTTP request below for requesting authorization.


GET /auth/authorize


response_type = code,
client_id = {your_client_id},
scope = {your_scope},
state = {any_text_you_want_to_put_here} //optional

2. If your access is authorized by the user, the following parameters will be sent to the redirect_uri* specified in your app dashboard.

code = {authorization_code_given}
state = {the_state_you_specified_in_step_1} //optional

3. Exchange the access token with the code you received in step 2.

Use HTTP request below for exchanging the access token.


POST /auth/token


grant_type = authorization_code,
client_id = {your_client_id},
client_secret = {your_client_secret},
code = {code_you_got_in_step_2},
state = {any_text_you_want_to_put_here} //optional

4. If your credentials are authenticated, a HTTP 200 will be sent back to you with the following parameters.

access_token = {access_token_given},
expires_in = 86400,
state = {state_you_specified_in_step_3} //optional

5. Access the protected resource with the access token.