These instructions describe how to add a transfer service node to Aspera on Cloud by using the Files API. In the following steps, you create an access key for the transfer service, augment the access key for use with Aspera on Cloud, and then create the node.

Prerequisites

  • An Aspera on Cloud account.
  • The user who performs this process must be an Organization Admin and ATS Admin. The user must also have their SSH private key set in their Aspera on Cloud user profile. For instructions, see the link in step 1 of the following instructions.

Creating the Node

  1. Create a bearer token for the Files API.

    For instructions, see Creating an Aspera on Cloud Bearer Token.

  2. Create an access key for your cloud storage.

    For instructions, see Creating Transfer Service Access Keys with the ATS API.

  3. Retrieve your organization key:
    curl -i -H "Authorization: Bearer token_string" -X GET https://api.asperafiles.com/api/v1/organization

    In the response, the organization key is the value for oauth_token_verification_key:

    HTTP/1.1 200 OK
    {
    "access_token_duration":3600,
    ...
    "oauth_token_verification_key":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAEINFE239523AQEAnBCh5I26tDTVi/JjTyWj\nB5fnWpOlEBz35TV3zolSJD2Du3gV6Kzafo33iNe4rOpx5j+uoSMNMoClRlH4BFYt\n6HcicPDWrxlxZYkwvxxcNwj2+RYGiNHMy4QleIAnBRvOl0iS3QWkMaUKQP09mUQA\nsmqoyhtKSscTYw+bwKufIzy4fdRbEluX/G26tpQDabxQrJ0LWI8PK9cbk56KwqMz\nbmxGt6iRsBQtf4hlQ0XLnY2Tas1cTeG7D/7HWrPl+JNWxStFh6ppICuuv8aWJayE\niGiTWbU1CdTrBpLPIc/3kl25M5BT8ENQZ9Bq1IVqcNv8QA4ewo3yg2vkCvxNs2pt\nIQIDAQAB\n-----END PUBLIC KEY-----\n",
    ...
    }
  4. Add the organization key to the access key and enable required server settings:
    curl -i -X PUT https://api.asperafiles.com/api/v1/ats/pub/v1/access_keys/{access_key_id} \
    -H "Authorization: Bearer token_string" \
    -H "Accept: application/json, text/plain, */*" \
    --data-binary "{ 
        "token_verification_key":"{org_oauth_key}", 
        "configuration": {  
            "server": {  
                "activity_event_logging":true,  
                "recursive_counts":true  
    } } }"

    For example,

    curl -i -X PUT https://api.asperafiles.com/api/v1/ats/pub/v1/access_keys/{access_key_id} -H "Authorization: Bearer abcdefg==" -H "Accept: application/json, text/plain, */*" --data-binary "{"token_verification_key":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAEINFE239523AQEAnBCh5I26tDTVi/JjTyWj\nB5fnWpOlEBz35TV3zolSJD2Du3gV6Kzafo33iNe4rOpx5j+uoSMNMoClRlH4BFYt\n6HcicPDWrxlxZYkwvxxcNwj2+RYGiNHMy4QleIAnBRvOl0iS3QWkMaUKQP09mUQA\nsmqoyhtKSscTYw+bwKufIzy4fdRbEluX/G26tpQDabxQrJ0LWI8PK9cbk56KwqMz\nbmxGt6iRsBQtf4hlQ0XLnY2Tas1cTeG7D/7HWrPl+JNWxStFh6ppICuuv8aWJayE\niGiTWbU1CdTrBpLPIc/3kl25M5BT8ENQZ9Bq1IVqcNv8QA4ewo3yg2vkCvxNs2pt\nIQIDAQAB\n-----END PUBLIC KEY-----\n","configuration":{"server":{"activity_event_logging":true,"recursive_counts":true}}}"
  5. Set permissions on the access key to allow Aspera on Cloud to edit it. The request syntax is the same as the previous step except for the data payload:
    curl -i -X PUT https://api.asperafiles.com/api/v1/ats/pub/v1/access_keys/{access_key_id} ... --data-binary "{"file_id":"1","access_level":"edit","access_type":"user","access_id":"F4 System"}"

    For example,

    curl -i -X PUT https://api.asperafiles.com/api/v1/ats/pub/v1/access_keys/{access_key_id} -H "Authorization: Bearer abcdefg==" -H "Origin: https://example.ibmaspera.com" -H "Accept-Encoding: gzip, deflate, br" -H "Accept-Language: en-US,en;q=0.9" -H "Accept: application/json, text/plain, */*" -H "Referer: https://example.ibmaspera.com/admin/nodes/new" -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36" -H "Connection: keep-alive" --compressed --data-binary "{"file_id":"1","access_level":"edit","access_type":"user","access_id":"F4 System"}"
  6. Create the node.
    curl -i -H "Authorization: Bearer token_string" -X POST https://api.asperafiles.com/api/v1/nodes -d@request_body.json

    Where request_body.json contains the following:

    {
        "name" : "node_name",
        "url" : "ats_endpoint",
        "access_key" : "access_key_id",
        "ats_access_key" : true,
        "ats_storage_type" : "type"
    }

    For example:

    curl -i -H "Authorization: Bearer abcdefg==" -X POST https://api.asperafiles.com/api/v1/nodes -d'{"name":"s3_east","url":"https://ats-aws-us-east-1.aspera.io:443/","access_key":"zyxwv","ats_access_key":true,"ats_storage_type":"aws_s3"}'

    A successful request returns a response similar to the following:

    {
        "access_key": "zyxwv",
        "capabilities": null,
        "configuration_policy_id": null,
        "host": "ats-aws-us-east-1.aspera.io",
        "id": "1234",
        "name": "s3_east",
        "path": "/",
        "port": 443,
        "settings": null,
        "status": "ok",
        "url": "https://ats-aws-us-east-1.aspera.io:443/",
        "use_ssl": true,
        "verify_ssl_certificate": true,
        "network_policy_id": null,
        "ats_access_key": true,
        "ats_storage_type": "aws_s3",
        "ssh_fingerprint": null
    }