/files/upload_setup

FASP transfers can use transfer tokens to authorize the transfer. Transfer tokens are the most restrictive of the tokens and require careful configuration. For more information, see Transfer Authentication and Authorization.

Requirements
  • Available as of Enterprise Server version 3.0.0.
  • The transfer user must be configured on the server for token authentication.
  • The default token life is 24 hours (86400 seconds), which is read from the server's aspera.conf. To change the token life, run the following command:
    # asconfigurator -x "set_node_data;token_life_seconds,seconds"
Access Control
  • HTTP Basic Auth
    Users who authenticate with Node API credentials can create upload tokens for files that are within their docroot. Access key users can create upload tokens for files that arre within the path set in the access key.
URL
POST https://{domain}:9092/files/upload_setup

Sample Request
curl -i -u user:secret -X POST https://{domain}:9092/files/upload_setup \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d @request_body.json

Where request_body.json contains the following:
{
    "transfer_requests" : [
        {
             "transfer_request" : {
                "source_root" : "optional/source/root_dir",
                "destination_root" : "optional/destination/root_dir",
                "token_life_seconds" : 43200,
                "paths" : [
                    {
                        "source" : "path/to/file",
                        "destination" : "path/to/other/file"
                    }
                ],
                "remote_host" : "host_address",        
                "cipher_allowed" : "aes-128",
                "content_protection" : "encrypt",
                "cookie" : "text",
                "fasp_port" : int,
                "ssh_port" : int
                "http_fallback" : bool,
                "http_fallback_port" : int,
                "https_fallback_port" : int,
                "rate_policy_allowed" : "low",
                "rate_policy" : "low",
                "target_rate_cap_kbps" : int,
                "target_rate_kbps" : int,
                "tags" : {
                    "aspera" : {
                        "usage_id" : "transfer_usage_id"
                    }
                },
            },
        "aspera_connect_settings" : {...}
        }
    ]
}

Headers
Header Name Required Description Values
Content-Type Optional The format of the request data. application/json
Accept Optional The format of the response data. application/json
Request Body

Note: Transfer specifications that are set in aspera.conf overwrite the corresponding values in the request body when the token is created.

Field Optional/Required Type Description
transfer_requests Required JSON The JSON object that contains the transfer request information. Multiple transfer requests can be included as comma-delimited transfer_request objects, if needed.
transfer_request Required JSON The JSON object that contains the transfer specification. The user is only allowed to upload the specified files with the specifed parameters, within the token lifetime.
source_root Optional String The source root directory of the files.
destination_root Optional String The destination root directory.
token_life_seconds Optional Number How long the token is valid after creation, in seconds. This option overrides the server setting. Available as of version 3.6.3.
paths Required JSON Array of JSON objects containing source paths. Destination paths are optional. Set as "*" to allow downloads of the source_root itself or any files within it.
source Optional String Source file pathname.
destination Required String Destination pathname.
remote_host Required String IP or fully qualified domain name of the remote server
cipher_allowed Optional String The algorithm that is used to encrypt data during a transfer. Use this option when transmitting sensitive data. Increases CPU utilization. Allowed values: none, aes-128, aes-256. Default: none.
content_protection Optional String Enable content protection (encryption-at-rest), which encrypts files when they are uploaded to the server and decrypts files when they are downloaded. Allowed values:
  • encrypt: Encrypt uploaded (on the server).
  • decrypt: Decrypt downloaded files. If content_protection_word is not specified, Connect will prompt for the passphrase.
  • Default: decrypt
content_protection_password Optional String Password to apply or remove encryption. Must be provided when content_protection is used.
cookie Optional String Metadata to associate with the transfer. The cookie is reported to both client- and server-side applications that are monitoring FASP transfers. Default: none
fasp_port Optional Unsigned integer The UDP port for FASP to use. The default value works for most situations; however, it can be changed to satisfy firewall requirements. Default: 33001
ssh_port Optional Unsigned integer The server's TCP port that is listening for SSH connections. FASP® initiates transfers through SSH. Default value: 33001
http_fallback Optional Boolean If set to true, the transfer attempts an HTTP or HTTPS transfer if FASP transfer errors. Default: false.
http_fallback_port Optional Unsigned integer The port that is used for HTTP transfers. If a cipher is enabled, the default is 443; otherwise, the default is 80.
https_fallback_port Optional Unsigned integer The port that is used for HTTPS transfers. If a cipher is enabled, the default is 443; otherwise, the default is 80.
rate_policy_allowed Optional String The most aggressive rate policy that is allowed for the transfer. See rate_policy for values.
rate_policy Optional String The congestion control behavior to use when sharing bandwidth. Allowed values:
  • high: When sharing bandwidth, transfer at twice the rate of a transfer using a "fair policy.
  • fair (default value): Share bandwidth equally with other traffic.
  • low: Use only un-utilized bandwidth.
  • fixed: Transfer at the target rate, regardless of the actual network capacity. Do not share bandwidth. The fixed policy can decrease transfer performance and cause problems on the target storage.
target_rate_kbps Optional Unsigned integer The desired speed of the transfer, in Kbps. If there is competing network traffic, FASP shares this bandwidth, depending on the rate_policy. Default is set on the server in the configuration file (aspera.conf). Will respect both local- and server-side target rate caps if set. Must be provided when you set a value for target_rate_cap_kbps.
target_rate_cap_kbps Optional Unsigned integer Upper limit of target rate, in Kbps. Default: no limit
tags Optional JSON Tags to describe the transfer that can be used as search terms.
aspera_connect_settings Optional JSON For more information on Connect settings, see Transfer Specifications.
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

{
    "transfer_specs" : [
        {
            "transfer_spec" : {
                "paths" : [
                    {
                        "destination" : "/Users/aspera/Documents/*"
                    }
                ],
                "source_root" : "",
                "destination_root" : "",
                "token" : "ATB2_ACsjPbserJSER32u-FHp6BsERNE3834UgE_2BTA",
                "direction" : "send",
                "cipher" : "aes-128",
                "tags" : null,
                "rate_policy_allowed" : "fair",
                "rate_policy" : "fair",
                "target_rate_kbps" : 45000,
                "min_rate_kbps" : 0,
                "remote_host" : "10.0.0.1",
                "remote_user" : "aspera",
                "sshfp" : null,
                "ssh_port" : 33001,
                "fasp_port" : 33001,
                "http_fallback" : true,
                "https_fallback_port" : 8443
            }
        }
    ]
}

Status Codes and Errors
Code Description Notes
200 OK Success
400 Bad Request Error Request contains a formatting or syntax error.
404 Not Found Error Invalid pathnames.
500 Internal Server Error Error The server configuration is invalid.
Response

The response body includes the transfer specification from the request body with the following additional parameters:

Element Type Description
token String The token string.
direction String For uploads, the value is send.
cipher String The cipher that is applied to the transfer.
remote_host String The IP address of the node that is the source of the download.
remote_user String The system user that authenticates the SSH connection for the transfer.
sshfp String The node's SSH fingerprint, if it is configured in the node's aspera.conf.
Video player

Video

×