Skip to content

Authentication

All requests to the Batch Updater API require authentication. The Batch Updater API uses tokens for authentication.

Users can obtain API keys via the Auth Service UI at https://www.dev.immport.org/auth/api/keys (create an API key with the appropriate scopes) using the UI.

This can be done by executing the following curl command:

Shell Command

# Use the API Keys UI at https://www.dev.immport.org/auth/api/keys to create an API key, then set it in $token:
# export token="REPLACE_WITH_API_KEY"
Results 
{
  "status" : 200,
  "token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXV............"
}

The token returned is a JWT token. (You can go to the JWT token URL and enter the token got from the above endpoint. This will give the information that the token contains. The token has information about the username, roles, permissions for the user.

The token must be used to initiate a API request within 60 secs. After 60 secs the token will be invalid and the user will need to get a new token. But once the GET endpoint is initiated then the token will be valid throughout the entire api request endpoint and does not become invalid until the response is returned.

Using the Authentication Token

All API requests require authentication. They must include the authentication token as an Authorization: bearer in the custom HTTP header.

In the following example, an authentication token is saved as an environment variable (token) and passed to the HTTP header in the curl command to get back the generated documentation specific to a workspace.

The following is an example of a request to the documentation generation endpoint with a single parameter (WORKSPACE_ID=REPLACE_WITH_WORKSPACE_ID).

Shell Script - Retrieve Templates

#!/bin/bash

# Obtain an API key from https://www.dev.immport.org/auth/api/keys (scopes: browse, download, upload)
# Set it into the existing $token variable so the examples below keep working.
export token="REPLACE_WITH_API_KEY"

curl -k -H "Authorization: bearer $token" https://immport-upload.niaid.nih.gov:9443/data/batch/updater/documentation/templates
Results 
templates.zip

First step is to fetch API key from https://www.dev.immport.org/auth/api/keys (create an API key with the appropriate scopes). Use that API key as a Bearer token in the Authorization header.

The second line is a Non-POST endpoint on the URL https://immport-upload.niaid.nih.gov:9443/data/batch/updater/documentation/templates/REPLACE_WITH_WORKSPACE_ID with the parameter REPLACE_WITH_WORKSPACE_ID. The authentication token ("token") is passed in the HTTP header as shown.

The response will return zip-file containing the template documentation specific to workspace whose workspace_id = REPLACE_WITH_WORKSPACE_ID.

The above shell script or any code starting with #!/bin/bash can be copied to a .sh file (e.g. documentationGeneration.sh )and executed at the command prompt of a terminal and the output can be directed to a file. (Please replace the REPLACE_WITH_USERNAME with your username and REPLACE_WITH_PASSWORD with your password.)

./documentationGeneration.sh > ImmportBatchUpdaterTemplates.zip