Access controlled data files by linking your NIH account in Terra

Michael Baumann
  • Updated

Learn to use controlled-access data on Terra by linking your Terra user ID to your NIH authorization account. Linking to external servers allows Terra to automatically determine if you can access controlled datasets hosted in Terra (such as AnVIL and other data hosted by the Broad Institute) based on your valid dbGaP applications. Read on for project-specific screenshots and step-by-step directions.

How it works

If you are an NIH researcher with a dbGaP account, you can link your Terra user ID to your eRA Commons ID. AnVIL researchers must link Terra accounts in order to access and import controlled-access data files (i.e., CRAMS and VCFs).

What data access this covers

  • AnVIL data workspaces
  • Data in the Terra Data Repository

Open-access dataYou can access open-access data in AnVIL without linking an NIH authorization account.

Step 1: Set up an NIH account

Before following the steps below, you will need an NIH (eraCommons) account. See for more details.

Step 2: Link your Terra profile to NIH authorization

2.1. Go to the main navigation menu by selecting the three horizontal lines at the top left of any page in Terra

2.2. Click on your name to expand and then on Profile.

  • Terra platform

    Terra homepage highlighting Profile in left-side hamburger menu

  • AnVIL on Terra
    AnVIL on Terra highlighting Profile in left-side hamburger menu

2.3. Click the EXTERNAL IDENTITIES tab.

Profile page with the EXTERNAL IDENTITIES tab highlighted

2.4. Click the button to log into NIH under External Identities.


You'll be taken to an external authentication webpage. Follow the instructions to link your accounts.

NIH authentication screenshot (AnVIL example)

NIH-authentication screenshot AnVIL example showing Smart Card login

2.5. Once you're linked, you'll see a link expiration deadline.


Finding the data you're authorized to useClick on the sections under Resources for a full list of datasets you’re authorized and not authorized to access.

Expanded menu


When to expect access (wait before submitting a support ticket!!)If you have access already (more than a day), you can expect to access your data in Terra six hours after linking your account. 

If you were just granted access to a dbGaP study, it can take up to 30 hours for your data to be available for analysis in Terra. 

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

Links expire after 15 days and you'll need to renew your link to access data.

Renewing your account link

Select the Renew link and follow the 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.

EXTERNAL IDENTITIES tab in the Profile page with the Unlink option highlighted under the NIH account link.



Was this article helpful?

0 out of 0 found this helpful



Please sign in to leave a comment.