-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Many minor improvements to the token docs
1. Run through prettier - normalize spacing and line length 2. Remove PyCharm wrap on typing for Markdown (so it does not break up <img> tags) 3. Minor grammar/typo fixes 4. Add alt-text for each image 5. Rename images to be consistent and to not bother the spell checker 6. Reduce all heading levels by 1. FHIR-1750
- Loading branch information
1 parent
f8339ce
commit 23dcfd8
Showing
4 changed files
with
36 additions
and
58 deletions.
There are no files selected for viewing
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
File renamed without changes
File renamed without changes
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,123 +1,101 @@ | ||
| # Obtaining a token to access dbGaP data | ||
|
|
||
| ## Obtaining a token to access dbGaP data | ||
| The following describes a simple web application to obtain a "passport" or token to access controlled access data via programmatic interfaces (APIs). It requires you to log in to dbGaP and download a file containing a token which can be used in calls to the APIs. | ||
|
|
||
| The following describes a simple web application to obtain a "passport" or token to access controlled access data via programmatic interfaces (APIs). It requires you to log in to dbGaP and download a file containing a token which can be used in calls to the APIs. | ||
| ## Note on use of controlled access data | ||
|
|
||
| ### Note on use of controlled access data | ||
| Your access to controlled data is granted under a project previously | ||
| submitted by an investigator. You, the user, may be that investigator, or have been designated by that investigator as a 'downloader'. The specific terms of use are described in a Data Use Agreement. Please ensure you are familiar with the terms of use. | ||
|
|
||
| Your access to controlled data is granted under a project previously submitted by an investigator. You, the user, may be that investigator, or have been designated by that investigator as a 'downloader'. The specific terms of use are described in a Data Use Agreement. Please ensure you are familiar with the terms of use | ||
| ## Obtain a token or passport | ||
|
|
||
|
|
||
|
|
||
| ### Obtain a token or passport | ||
|
|
||
| In a web browser, open the following link to open the Power User Portal | ||
| In a web browser, open the following link to open the Power User Portal | ||
|
|
||
| https://dbgap.ncbi.nlm.nih.gov/cda/dbGaPLogin/ | ||
|
|
||
| <img src="./img/token-choose.jpg" alt="token-choose" style="zoom:33%;" />You may request a passport or a task specific token. Each may be used as follows: | ||
| <img src="./img/token-choose.jpg" alt="The main power-user portal page. It has options for obtaining a RAS passport or a Task-Specific Token" style="width:100%;height:auto;" />You may request a passport or a task specific token. Each may be used as follows: | ||
|
|
||
| #### Passport | ||
| ### Passport | ||
|
|
||
| May be used with the NCBI Data Repository Service (DRS<sup>1</sup>) to access files. | ||
| May be used with the NCBI Data Repository Service (DRS<sup>1</sup>) to access files. | ||
|
|
||
| - Click **Get My Passport**. | ||
| - Go to **Login** below | ||
|
|
||
| ### Task Specific Token | ||
|
|
||
| #### Task Specific Token | ||
|
|
||
| May be used with NCBI DRS or FHIR server. | ||
| May be used with NCBI DRS or FHIR server. | ||
|
|
||
| Scroll down to the "RAS - Obtain a dbGaP Task Specific Token" | ||
|
|
||
| <img src="./img/token-tst.jpg" alt="token-tst" style="zoom:33%;" /> | ||
| <img src="./img/token-tst.jpg" alt="The RAS Task Specific Token (TST) section of the power user portal. It has a button labeled "Get Task Specific Token"" style="width:100%;height:auto;" /> | ||
|
|
||
| - Click Get **Task Specific Token** - Go to **Login** below | ||
|
|
||
|
|
||
| <sup>1</sup>DRS is a standard published by the Global Alliance for Genomics and Health (GA4GH). | ||
|
|
||
| ## Login | ||
|
|
||
| Whether you picked Passport or Task Specific Token you will be asked to log in using the appropriate method depending on the organization you work for. | ||
|
|
||
| <img src="./img/token-nihlogin.jpg" alt="token-nihlogin" style="zoom:33%;" /> | ||
| # Login | ||
|
|
||
| Whether you picked Passport or Task Specific Token you will be asked to log in using the appropriate method depending on the organization you work for. | ||
|
|
||
| <img src="img/token-nih-login.jpg" alt="A web page entitled "Sign in" with the option to use a smart card login or an authenticator app combined with username and password" style="width:100%;height:auto;" /> | ||
|
|
||
| The next steps depend on whether you are obtaining a Passport or TST. | ||
|
|
||
| ### Passport | ||
| ## Passport | ||
|
|
||
| After logging in Click **Download** to save the passport to a local file according to how your web browser is set up to handle downloads. | ||
|
|
||
| You have now obtained the passport required by the API you wish to use it with. | ||
|
|
||
| ### Task Specific Token | ||
| ## Task Specific Token | ||
|
|
||
| Select the dbGaP project you wish to work with and download the token as follows. | ||
| Select the dbGaP project you wish to work with and download the token as follows. | ||
|
|
||
| ### Select dbGaP project | ||
|
|
||
| The one or more dbGaP projects under which you have been granted access will be listed. | ||
| The one or more dbGaP projects under which you have been granted access will be listed. | ||
|
|
||
| For each project the investigator will have requested access to certain dbGaP study consent groups<sup>2</sup>. Click the checkbox next to the project you wish to work with. | ||
| For each project, the investigator will have requested access to certain dbGaP study consent groups<sup>2</sup>. Click the checkbox next to the project you wish to work with. | ||
|
|
||
| <sup>2</sup>a consent group is a group of subjects within a study who consented to use of their data under particular terms. | ||
| <sup>2</sup>A consent group is a group of subjects within a study who consented to use of their data under particular terms. | ||
|
|
||
| #### Single project displayed | ||
|
|
||
| For most users only one project will be displayed. In this case you may simply select the project and click **Submit**. | ||
|
|
||
| Note: the individual study consent groups within the project will be displayed, and all are pre-selected. It is currently possible to select only specific study consent groups - but this is generally unnecessary. In the interests of simplification this feature will be removed in future. | ||
| Note: the individual study consent groups within the project will be displayed, and all are pre-selected. It is currently possible to select only specific study consent groups - but this is generally unnecessary. We will remove this feature in the future to simplify the interface. | ||
|
|
||
| #### Multiple projects displayed | ||
|
|
||
| In the case where more than one project is available the following apply: | ||
|
|
||
| It is possible to make selections of consent groups from more than one project. In general you should avoid this. Access to studies was granted according to the purposes of the submitted project. Combining data from studies across projects may be outside the terms under which access was granted. | ||
| It is possible to make selections of consent groups from more than one project. In general, you should avoid this. Access to studies was granted according to the purposes of the submitted project. Combining data from studies across projects may be outside the terms under which access was granted. | ||
|
|
||
| <img src="./img/token-project.jpg" alt="token-project" style="zoom:33%;" /> | ||
| <img src="./img/token-project.jpg" alt="A list with two entries, "Engineering a centralized approach for the analysis of NIH-funded human sequence data."e and "Scientific and technical management of data commons projects at NIH" Each entry has a check box on the right and a "plus" icon on the right one may click to expand to see the options under it." style="width:100%;height:auto;" /> | ||
|
|
||
| Scroll down and select **Submit**. | ||
| Scroll down and select **Submit**. | ||
|
|
||
| ## Select token duration | ||
| ### Select token duration | ||
|
|
||
| Choose how long you would like the token to be valid, and click **Submit**. | ||
|
|
||
| <img src="./img/token-duration.jpg" alt="token-duration" /> | ||
|
|
||
|
|
||
| <img src="./img/token-duration.jpg" alt="A radio box entitled "Select token duration from this list." It has four choices: 1 minute, 10 minutes, 1 hour, and 12 hours." style="width:100%;height:auto;" /> | ||
|
|
||
| ## Confirm details | ||
| ### Confirm details | ||
|
|
||
| Click **Confirm** if you are happy with the selections made. | ||
|
|
||
| You may click **Re-Select** to return to the project selection page | ||
|
|
||
| <img src="./img/confirm.jpg" alt="Graphical user interface Description automatically generated" style="zoom:33%;" /> | ||
|
|
||
| ## Download | ||
|
|
||
| Click **Download** to save the token to a local file. | ||
|
|
||
|
|
||
|
|
||
| <img src="./img/token-download.jpg" alt="Graphical user interface, text, application, email Description automatically generated" style="zoom:33%;" /> | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| Use the downloaded token with the API you wish to use. Consult the API documentation for how to include the token in your request to the API. | ||
|
|
||
| ------ | ||
|
|
||
|
|
||
| <img src="./img/confirm.jpg" alt="The bottom of a page. It displays several studies with their accession and a brief description. Each study is in black text on a gray background. Below is a field entitled "Selected Duration" containing the text "12 hours" Finally, at the bottom is a section entitled "Confirm your selections:" This section contains two buttons, Re-select and Confirm." style="width:100%;height:auto;" /> | ||
|
|
||
| ### Download | ||
|
|
||
| Click **Download** to save the token to a local file. Ensure only you can access the file. | ||
|
|
||
| <img src="./img/token-download.jpg" alt="A success screen containing the message "Hello. You have successfully logged into RAS. Click the Download button to download your NCBI Task-Specific-Token!." Below the message is a button labeled Download. At the bottom is a link to return to the dbGaP Authorized Access Portal." style="width:100%;height:auto;" /> | ||
|
|
||
| Use the downloaded token with the API you wish to use. Consult the API documentation for how to include the token in your request to the API. | ||
|
|
||
| --- |