How to authenticate/troubleshoot Swagger

Anton Kovalsky
  • 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.
Swagger_Find-authorize-button_Screenshot.png

1.3. Choose an authentication method: googleoauth or oidc.
- If you're running the createProfile endpoint to create a google-backed billing profile, use the googleoauth authentication and check all four boxes (including the last one about billing, which may not be checked by default).
- Otherwise, choose either authentication method, but not both.
- click Authorize again.

Swagger_Available-authorizations_Screenshot.png

1.4. If asked, select the email associated with the Billing Project that you'll be using to create the cloud environment.

1.5. When you close the authentication pop-up window, do not click Sign Out.

What to expect

After you've clicked "Authorize" and selected your login credentials (you may be asked for a password), you'll see the pop-up below. Make sure to click "close" and not "log off" to stay authenticated as you execute the API functions.

Swagger_Close-authorization-popup_Screenshot.png

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

2.4. Click Execute.  

Sep-23-2021_02-14-04.gif

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. 

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. 

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

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.