Learn to use controlled-access data on Terra by linking your Terra user ID to your authorization account (such as a dbGaP account). Linking to external servers allows Terra to automatically determine if you can access controlled datasets hosted in Terra (e.g., TCGA, TOPMed, etc.) based on your valid dbGaP applications. Read on for project-specific screenshots and step-by-step directions.
Access Gen3 data files by linking your Terra account
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).
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.
| AnVIL | https://gen3.theanvil.io/ |
| BioData catalyst | https://gen3.biodatacatalyst.nhlbi.nih.gov/ |
| NCI/TGCA | https://nci-crdc.datacommons.io/ |
Step 2: Link to external servers
1. Go to the main navigation menu by selecting the three horizontal lines at the top left of any page in Terra
2. Click on your name to expand and then on Profile.
-
Terra platform
-
AnVIL on Terra
-
BioData Catalyst on Terra
3. On the right-hand side of your profile page under Identity & External Services, link to the relevant server.
When you select a link, you'll be taken to an external authentication webpage. The authentication will automatically match the way you authenticated on the Gen3 platform (Google versus NIH versus RAS, for example). Follow the instructions to link your accounts.
-
Google login screenshot (AnVIL instance)
-
NIH authentication screenshot (AnVIL example)
4. Once you're linked, you'll see a link expiration deadline for each external service.
Pay attention to the expiration deadlines! If your link expires, any attempt to access/import data/or manipulate files from the Terra platform will result in an error indicating a user is not authorized to access 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'll need to renew your link to access data.
To renew linksSelect the "Log-in to Framework services..." link and follow instructions. You can relink your account at any time. See a BioData Catalyst example in the screenshot above.
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 (to reset the 15-day timer) by clicking Unlink at the end of your session and/or Renew when starting your work
