Token Generation (Node API)

A token authorizes content uploads to a destination or content downloads from a remote source. Token-based authorization is generally used instead of SSH authentication for FASP transfers initiated through IBM web applications, such as IBM Aspera Shares, Faspex, and Sharepoint, but can be used in place of SSH authentication for other types of Aspera products. When a user requests a transfer from Shares. Faspex, or Sharepoint in the web UI, an operational token is automatically generated using the Node API and is used to authorize the ascp session between the client and the Shares, Faspex, or Sharepoint node, within constraints set in the command line and aspera.conf.

Aspera recommends using the Node API tool to generate tokens, though they can be generated using the astokengen tool. Using the Node API tool enables greater flexibility and functionality because astokengen creates tokens constrained by the settings in aspera.conf. In practice, astokengen is most useful for decoding tokens during application development for debugging purposes. For more information on astokengen, see Token Generation (astokengen).

For more information on using the Node API, request access to the Aspera Developer Network (ADN) from your Aspera account manager.

Prerequisite: Setup for Token Authorization

Before generating and using tokens, you must set up a transfer user for token authorization and associate the transfer user with a node username and password. For instructions, see Setting Up Token Authorization.

Generating Tokens with Node API Calls

Curl is used to call the API, and is freely available for download for all operating systems supported by Aspera from:

https://curl.haxx.se/

To generate a token, you run a curl command to the /files/upload_setup or /files/download_setup endpoint (depending on what kind of token you want to generate). The request provides a JSON Object called the transfer_requests. The Node API output response, a transfer_specs JSON Object, includes a token, as well as a description of who is authorized to transfer using the token, what files can be transferred, and transfer properties.

Note: When generating tokens with an IBM Aspera Shares server, the endpoints are /node_api/files/upload_setup and /node_api/files/download_setup.

Upload token

General syntax:

# curl -i -X POST -u node_username:node_user_password -d '{"transfer_requests" : [{"transfer_request" : { "paths" : [{}], "destination_root" : "/" } } ] }";' http(s)://node_server:node_port/files/upload_setup

This command specifies the following:

  • -i Include the HTTP header in the output.
  • -X POST Specify a POST request to the HTTP server, rather than the default GET request. (This option is not required when -d is used, but is included here for completeness).
  • -u node_username:node_user_password Authenticate using the node username and node user password that are associated with the transfer user who has been configured for token authorization.
  • -d Send the specified data payload to the HTTP server. The payload can be entered in the command line, as it is here, or stored in a file, as described below.
  • http(s)://... The endpoint URL.

For example, the following request allows the user, lion, who is associated with the node username, nodeuser, and node username password, nodepassword, to upload any files from the source to any location on the destination, serengeti.com:

# curl -i -v -X POST -u nodeuser:nodepassword -d '{ "transfer_requests" : [ { "transfer_request" : { "paths" : [{}], "destination_root" : "/" } } ] }";' http://serengeti.com:9091/files/upload_setup

The response output is the following, from which you can extract the token string ATV7_HtfhDa-JwWfc6RkTwhkDUqjHeLQePiOHjIS254_LJ14_7VTA:

HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/x-javascript
{
	"transfer_specs" : [{
		"transfer_spec" : {
				"paths" : [{}],
				"source_root" : "",
				"destination_root" : "/",
				"token" : "ATV7_HtfhDa-JwWfc6RkTwhkDUqjHeLQePiOHjIS254_LJ14_7VTA",
				"direction" : "send",
				"target_rate_cap_kbps" : 100000,
				"cipher" : "none",
				"rate_policy_allowed" : "fair",
				"rate_policy" : "fair",
				"target_rate_kbps" : 45000,
				"min_rate_kbps" : 0,
				"remote_host" : "serengti.com",
				"remote_user" : "lion",
				"ssh_port" : 22,
				"fasp_port" : 33001,
				"http_fallback" : true,
				"http_fallback_port" : 8080
		}
	}]
}

You can also specify the transfer request parameters in a file and refer to it in the curl command, which is particularly useful for transfer requests that list many items for source content and destination. For example, the transfer request file, upload_setup.json, could contain the following information for a file pair list:

{
   "transfer_requests" : [
      {
         "transfer_request" : {
            "destination_root" : "/",
            "paths" : [
              {
                 "destination" : "/archive/monday/texts/first_thing",
                 "source" : "/monday/first_thing.txt"
              },
              {
                 "destination" : "/archive/monday/texts/next_thing"
                 "source" : "/monday/next_thing.txt",
              },
              {
                 "destination" : "/archive/monday/texts/last_thing",
                 "source" : "/monday/last_thing.txt"
              }
           ]
         }
      }
   ]
}

To use this file in the curl command, specify the path to the file in the -d option, as follows:

-d @upload_setup.json

Download token

The method for generating a download token is the same as for an upload token, except that you use the /files/download_setup (or /node_api/files/download_setup in the case of Shares) endpoint.

Using Tokens in the Command Line

Once the token is generated, it can be used to authorize FASP transfers by setting the ASPERA_SCP_TOKEN environment variable or using the -W option for ascp and async sessions.