How to authenticate/troubleshoot Swagger for TDR

Leyla Tarhan
  • Updated

All instructions related to Swagger require you to first authenticate yourself whenever you’ve opened a window with the Swagger UI. Below are detailed instructions on how to make sure you are fully authenticated when using Swagger API functions, and some troubleshooting tips to keep you on track.

When does authorization expire?

Opening new tabs, running into errors/failures, refreshing your page, or letting enough time go by can all cause your authentication to expire. If you're getting errors (especially 401 errors or any kind of "unauthorized" errors), try to re-authenticate using the instructions below.

Step 1. Authenticate your credentials on Swagger

1.1. Go to the Swagger UI page for the service that you want to access via API. Note that TDR and notebooks have separate Swagger pages!

TDR and notebooks Swagger pages

  • Terra Data Repository
    Find API endpoints for the TDR (where you'll find the commands necessary for ingesting data) at https://data.terra.bio/swagger-ui.html.
  • Notebooks
    For notebooks, API commands for doing things like creating or deleting virtual machines or persistent disks can be found at notebooks.firecloud.org.

1.2. Click the Authorize button at the right, near the top of the page.
Screenshot of the TDR API endpoints on Swagger. An orange arrow highlights the 'Authorize' button at the top right of the screen.

1.3. Click Authorize again in popup "Available authorizations" window. 

Screenshot of the available authorizations popup window. An orange rectangle highlights the 'authorize' button.

1.4. You will be redirected to a Terra login screen. Click Sign in with Google to log in using Google credentials or Sign in with Microsoft to log in using Microsoft credentials. 

Screenshot of the Terra login screen, with options to sign in with Google or Microsoft credentials.

Should you log in with Google or Microsoft? In most cases, you can choose to authenticate Swagger using either Google or Microsoft credentials. The credentials you use to authenticate Swagger are unrelated to the cloud provider you're using to power your data and analyses. For example, you can authenticate using a Google email to manage an Azure-backed dataset, or vice versa.

However, if you are running an API job to create or update a Google-backed billing profile, you must log in using Google. Otherwise, choose whichever Single Sing-on (SSO) provider you use to sign into Terra or the Terra Data Repository.

1.5. Enter your login credentials -- the same email and password you use to sign into Terra (https://app.terra.bio/) and the Terra Data Repository (https://data.terra.bio/). 

1.6. If asked, authorize b2clogin to access your Google or Microsoft account.

1.7. When you're redirected back to the Swagger UI, close the authentication pop-up window, but do not click Sign Out.

Screenshot of the available authorizations popup window, after Swagger has been authenticated. An orange rectangle highlights the 'close' button.

What to expect

Once you've authenticated your credentials, you should see a closed lock symbol on the "Authorize" button at the top right of the page. 

Screenshot of the top of the TDR Swagger endpoints screen. An orange rectangle highlights the 'Authorize' button on the right-hand side of the screen, where a closed lock symbol indicates that Swagger has been authenticated.

Getting errors and failures using Swagger? If you're already using Swagger, and you notice you're starting to get a lot of errors and failures, try refreshing the browser page, and continue following these instructions.

Step 2. Execute API functions

You can now use the API functions listed on the page. Note that the email you authenticated must be the same email you use to log into Terra. This should automatically be true if you are working in the same Chrome browser window.

2.1. Select the endpoint of interest to expand the details.

2.2. Click Try it out to activate the fields.

2.3. Fill in the request body and other fields. Some endpoints include additional documentation, which you can access by clicking Schema  or model above the request body.

2.4. Click Execute.  

Screen recording showing how to select a Swagger API endpoint, edit the request body, and submit a job.

What to expect

If you've done everything right, you should get a 200 message in the response field, as well as whatever output the API is supposed to return. In some cases, you will need to run a separate API to verify whether your job succeeded - for example, you might run the addProfilePolicyMember API to add a collaborator to a TDR billing profile, then run the retrieveProfilePolicies API to verify that collaborator was added.

Troubleshooting

401 errors

If you get a response that includes the word unauthorized, you likely need to re-authorize Swagger following the directions above. 

If you don't know if the job is finished

Some Swagger jobs take a long time to complete, and it is hard to tell if it is stuck, failed, or still running. If that's the case, you can use the jobs APIs to check on the status. 

1. Get the Swagger job ID

Use the enumerateJobs endpoint to get the Swagger job UUID. In some cases, you can also find this UUI in the output from your original API call. 

2. Get the job status

Use the retreiveJob endpoint to get the status of the job. You will use the UUID from step one in the ID field (under parameters). 

Alternatively, you can monitor jobs in the Activity tab of the Terra Data Repository web interface

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.