Generating an Alias Token for Scripted Authentication

In a scripted interaction with XNAT, you will need a way of authenticating your request so that XNAT can determine whether you are allowed to perform the action that you are requesting. The brute-force way to do this is to simply include your username and password on the command line in plain text, like so: 

$ curl -u USERNAME:PASSWORD http://10.1.1.17/data/projects

Note: this call will return a list of projects in XNAT accessible to the username provided. 

However, this is not a good practice, both for security reasons and for user session management. Every time you perform a REST call with a username:password combo, XNAT creates a new authenticated user session. Too many of these can overwhelm your Tomcat instance and cause it to freeze. 

Instead, we recommend using a combination of a user alias token and a JSESSION ID to authenticate our calls. Start by bringing up your XNAT. 

1. Log in to XNAT

2. Click on your username in the very top right navigation bar to go to your User Account page. 

3. Click on the "Manage Alias Tokens" tab. 

Manage Alias Tokens screen


4. Click "Create Alias Token". This generates a hashed combination of your user ID and password that can be used as login credentials temporarily until it expires. You can create and use as many as you need, and delete them or force them to expire as needed. (You can also create single-use tokens using the API, for added security.)  

Generated Alias Token


5. Click on the generated "Alias" link to view the full token. The fields you need as a substitute for your username:password are "alias" and "secret" 

View Alias Token


6. Copy the "alias" and "secret" strings and paste them into the following curl command in your Terminal window: 

$ curl -u ALIAS:SECRET http://10.1.1.17/data/projects?format=csv >> projects.csv

This command gets a list of projects in CSV format and outputs them to a file in your current local directory called "projects.csv". 


Deleting or Expiring an Alias Token

Since an alias token is a valid set of login credentials tied to your account, we don't want the token lasting for very long. It naturally expires in a short period of time, but you can also manually force a token to expire by logging in, navigating to your list of Alias Tokens, and clicking "Delete" in the table row for the token you wish to expire.

Related: User Alias Token API

$label.name