Transfer Token Creation (Node API)

Aspera recommends using the Node API tool to generate transfer 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.

Note: Transfer tokens for use with Ascp 4 must be created with astokengen. Otherwise, astokengen is most useful for decoding tokens during application development for debugging purposes. For more information on astokengen, see Transfer Token Generation (astokengen).

Prerequisites:

In order to create transfer tokens with the Node API, you must set up HST Server for the Node API. For instructions, see Node API Setup.

Creating Transfer 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:

https://curl.haxx.se/

To generate a token, 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 body includes 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 API username and 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 API username, nodeuser, and Node API 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 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 Transfer 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.