Learn to use controlled-access data from Gen3 on Terra by linking your Terra user ID to your authorization account (such as a dbGaP account). Linking your authorization lets Terra automatically determine if you can access controlled datasets based on your valid dbGaP applications. Read on for project-specific screenshots and step-by-step directions.
Note that AnVIL data is now provided through the AnVIL Data ExplorerThe AnVIL Gen3 data portal is no longer available.
Accessing AnVIL or TDR data?If you need to access data stored in the AnVIL or the Terra Data repository, see Access controlled data files by linking your NIH accoutn in Terra for step-by-step instructions.
Access Gen3 data files by linking your Terra account
As an example, if you are an NIH BioData Catalyst researcher with a dbGaP account, you can link your Terra user ID to your eRA Commons ID. BioData Catalyst researchers must link Terra accounts in order to access and import Gen3 data files (i.e., CRAMS and VCFs).
Compliance when using controlled-access dataWhen you import controlled-access data from external repositories to a Terra workspace with a Google billing project, additional security monitoring will be added to the workspace. This means that Terra will create an auditable log of the workspace's activity.
If you're having trouble accessing a workspace with controlled-access data, check that your external identity link has not expired and that your dbGAP or DUOS Data Access Request is valid.
Step 1: Log into Gen3
Before following the steps below, log into your Gen3 account. You can use either your NIH login or your Google login. When you link your account to Terra, Terra will know to use the same login.
| BioData catalyst | https://gen3.biodatacatalyst.nhlbi.nih.gov/ |
| KidsFirst DRC | https://data.kidsfirstdrc.org/ |
| NCI CRDC | https://nci-crdc.datacommons.io/ |
Step 2: Link authorization in Terra
2.1. Log into Terra (or your Terra-based platform) and go to the main navigation menu by selecting the three horizontal lines at the top left of any page.
2.2. Click on your name to expand and then on Profile.
-
Terra platform
-
BioData Catalyst on Terra
2.3. Click the EXTERNAL IDENTITIES tab.
2.4. Link to the relevant server by clicking its respective LOG IN button.
You will be taken to an external authentication webpage. The authentication method will automatically match the method you used on the Gen3 platform (Google versus NIH versus RAS, for example). Follow the instructions to link your accounts.
-
NIH authentication screenshot
-
Google login screenshot
What to expect
Once you've linked your account in Terra, you'll see a link expiration deadline for each linked external service in the External Identities tab of your profile menu. Links expire after 15 days.
Some data requires an NIH Account linkIf you are unable to access the data associated with your external server of choice, try also establishing a link on the NIH Account connection.
Check the expiration deadlines before starting an analysis If your link expires, any attempt to access, import, or manipulate data from the Terra platform will result in an error indicating that a user is not authorized to access the data. For example, if your link expires while you are running a multi-day workflow on imported data, the workflow will fail.
Please ensure all workflows on imported Gen3 data can finish before the expiration deadline. Links expire after 15 days, and you will need to renew your link to access or analyze data.
Renewing your account link
Select the Renew link for your external account in the External Identities tab of your profile menu, then follow the on-screen instructions. You can relink your account at any time, which will restart the 15-day link expiration time.
Unlinking your account
If you don’t renew your authorization links, you will get a notification that they have expired and you need to relink them. You can also do this proactively by clicking Unlink at the end of your session.
