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.
1.3. Click Authorize again in popup "Available authorizations" window.
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.
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 sign-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.
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.
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.
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