Transfer Token Creation (Node API)

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.

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 (or ascp4) and async sessions.