Linking authorization/accessing controlled data on external servers

Liz Kiernan

To use controlled-access data on Terra, you will need to link your Terra user ID to your authorization account (such as a dbGaP account). Linking to external servers will allow Terra to automatically determine if you can access controlled datasets hosted in Terra (ex. TCGA, TOPMed, etc.) based on your valid dbGaP applications. This article includes project-specific screenshots and step-by-step directions. 

Access Gen3 data files by linking your Terra account to external servers 

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).  


You must log into Gen3 first

Before following the steps below, you must 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.

Link to external servers: Step-by-step Instructions

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"

Expand for screenshots - Terra | BioData Catalyst | AnVIL

Terra platform

BioData Catalyst on Terra platform

AnVIL on Terra platform

Profile-menu_Terra_Screen_shot.png Profile-menu_BDC-on-Terra_Screen_shot.png Profile-menu_AnVIL-on-Terra_Screen_shot.png

3. On the right hand side of your profile page under "Identity & External Services", link to the relevant external servers:

AnVIL  NHGRI AnVIL Data Commons Framework Services
BioData catalyst NHLBI BioData Catalyst Framework Services
NCI/TGCA NCI CRDC Framework Services


When you select a link, you'll be taken to an external authentication webpage. The authentication will 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 
Links will expire after 30 days and you'll need to renew your link to access data, and more frequently for those using CDRC data - NCI CRDC Framework Services expiration occurs after only 15 days.




Warning: Pay attention to the expiration deadlines! 


If you are not linked 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.



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 data can finish before the expiration deadline.


G-_icon-warning.png To renew links, select the "Log-in to Framework services..." link and
follow instructions. You can re-link your account at any time. See a
BioData Catalyst example in the screenshot above.

Unlinking your account

If you don’t renew your account linkages after a long enough period, you will get a notification that they have expired and that you'll have to remove those linkages and then re-link them. You can also do this proactively by clicking "Unlink" at the end of your session and/or "Renew" when starting your work.


Was this article helpful?

0 out of 1 found this helpful

Have more questions? Submit a request



  • Comment author
    John-Hanson Machado

    Thanks for this!

    I previously had linked to my Terra Profile: NHLBI Biodata Catalyst Framework Services, NCI CRDC Framework Services, & NHGRI AnVIL Data Commons Framework Services. These links expired. The "Renew" link appears, but following this link in either Firefox or Chrome does not allow me to renew.

    I think this may have to do with the migration of eRA Commons to using, which is required by all users by September 15, 2021. Any idea how I can now use my credentials instead of eRA Commons when renewing expired access?


  • Comment author
    Liz Kiernan

    John-Hanson Machado thanks for letting us know about the issue.

    A colleague was able to replicate the error after associating their eRA Commons account with To resolve the issue, they logged out of eRA commons and refreshed the Terra profile page, then tried to renew the link in Terra again. Would you be able to see if it works for you? Thank you!

  • Comment author
    John-Hanson Machado
    • Edited

    Liz Kiernan thank you for your quick response.

    I could not see an option to log out of eRA Commons and my NIH account in the "Identity & External Servers" in the right pane of my profile, only a "Renew" option.

    I could, however, unlink the NHLBI BioData Catalyst, NCI CRDC Framework, & NHGRI AnVIL Data Commons, but when redirected by the link in Terra to enter my username and password, my credentials do not work here (login failed).

    I then clicked on "Trouble signing in?" and did not see as an option (not shown in images here). I also verified I had the correct username and password by going separately to and using those credentials to successfully sign in. What am I missing?

  • Comment author
    Samantha (she/her)

    Hi John-Hanson Machado,

    Renewing your access with credentials is currently not supported by RAS. Can you try signing in with your eRA commons account?



  • Comment author
    Florian Hölzlwimmer


    A student working with me does not have any dbGaP account.
    Is it possible for me to grant him access to my workspace even if it requires 'GTEx-dbGaP-Authorized' as authorization domain?

    Otherwise, it sounds like a hassle to request an NIH account + dbGaP access for every student in our lab, especially since dbGaP is not meant for this.


  • Comment author
    Samantha (she/her)

    Hi Florian Hölzlwimmer,


    You should be able to add your student as a data downloader so that he can access GTEx data: Assign Downloaders for dbGaP Data





Please sign in to leave a comment.