Purpose of this document

This document describes how to use the Files API to build a client application that enables a user to send digital files to another user. This file-sending capability is a fundamental function of Aspera Files.

Procedures in this document show how to enable an administrative user to:

  • Retrieve appropriate tokens.
  • Create the environment:
    • Client, including a whitelist of allowed users.
    • Workspace: the fundamental organizing container in a Files organization (see “Workspaces” in The Aspera Files API).
    • Users: one to send files and one to receive them.

Once the client application is established, a user of the app can then:

  • Retrieve appropriate tokens.
  • Select files to send.
  • Address to the recipient.
  • Initiate the transfer.

Getting started

This section contains the following topics:

  • Registration and app key
  • Authorization

Registration and app key

Before you can access the Files API, you must have an existing Files organization administrator do four things:

  1. Register your API client to generate a client ID and client secret to give to you. You pass the client ID and secret (either in the request body as parameters, or by means of basic authentication with the client ID as the username and secret as the password) to retrieve an admin-scoped bearer token. You provide this bearer token in all subsequent API calls. See the Authorization section.
    1. Create the client.
      GUI path: Organization > Integrations > Create new.
    2. Required: Enable client for JWT authentication.
      GUI path: Organization > Integrations > clientName > JSON Web Token Auth > Settings > Enable JWT grant type.
      (jwt_grant_enabled = true)
    3. Required: Enable to retrieve an admin token from the node.
      GUI path: Organization > Integrations > clientName > JSON Web Token Auth > Settings > Enable AoC administrators to retrieve a transfer node token that grants node administrator permissions.
      (admin_node_token_retrieval_enabled = true)
    4. Recommended: Enable client for whitelist of authorized users.
      GUI path: Organization > Integrations > clientName > JSON Web Token Auth > Client can retrieve tokens for: Only selected users.
      (whitelist_enabled = true)
      Once users are created in step 3 below, add them here.
    5. Give you the client ID and secret.
      GUI path: Organization > Integrations > clientName > Profile > Client info.
  2. Add you to the Files user database as an organization administrator; include your public key in your user record; you use the corresponding private key (.pem format required) to sign your calls to the API.
  3. Give you the node ID of a node with “status”: “ok” on which to place the workspace that you create in step 5 below.
  4. Verify that the Aspera transfer nodes that are the source and destination for your transfer are enabled for the Node API. Consult the IBM Aspera Enterprise Server guide or the IBM Aspera Connect Server guide.

Authorization

For every call to the Files API, you must supply a bearer token. Get a bearer token from Files API using your client.

This section assumes you are using the JWT grant type.

Introduction

IBM Aspera Files offers a JWT-based OAuth 2.0 grant type to enable client applications to use the Files API without a user having to log in from a web browser.

This flow utilizes an RSA keypair; the client’s public key is given to the server to verify a JWT that the client generates. These keypairs can be created on a per-client or per-user basis.

A public key defined on the client itself can be used to authenticate any user in the organization. Since no login prompt is presented, and the client will be able to act on behalf of any user, this should be used carefully only by highly trusted clients. An alternate authentication scheme may be added in the client as desired.

A public key defined on a particular user can only be used to authenticate that user. This is the preferred mode of operation, as a special user should be created for automated scripts to run as. If public keys are defined both on the client and user level, both will be tried when attempting to obtain a token.

Once a valid JWT token is presented to the server and verified, the server returns an OAuth 2.0 bearer token that can then be used by the client to make API calls.

The following instructions describe how to:

1. Set up the user who will send requests to the Files API, ATS API, or Node API.

2. Create an API client ID and secret, which are used to authenticate the request for the bearer token.

3. Create the JWT token request.

4. Create a Files bearer token.

5. Create a Node API bearer token.

Setting up the user and client

1. The user who will use the Files bearer token creates a private-public key pair by running the following commands:
$ openssl genrsa -out private_key.pem 2048
$ openssl rsa -in private_key.pem -pubout -out public_key.pem

2. The organization admin adds the user’s public key to their profile. Go to Admin > Users > username, paste the user’s public key into their profile. Click Save to activate your changes. This step can also be done through the Files API if the admin already has an admin-scoped bearer token.

3. Create a client ID and secret by registering an API client. The client must be configured to accept JWT tokens. You do not need to enter real values for Origin or Redirect URIs. For instructions, see the Registration and app key section.

Constructing a JWT token and creating a Files bearer token

1. The JWT token header is the same for all JWT tokens:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.

It is created by running the following command:
$ echo -n '{"typ":"JWT","alg":"RS256"}' | base64 | tr '+' '-' | tr '/' '_' | tr -d '='

2. Encode the JWT token payload by running the following command (with correct values):
$ echo -n '{"iss":"client_id","sub":"user_email_address","aud":"https://api.asperafiles.com/api/v1/oauth2/token","nbf":valid_start_time,"exp":token_expiration_time}' | base64 | tr '+' '-' | tr '/' '_' | tr -d '='

The payload has the following structure:
{
"iss": "
client_id",
"sub": "
user_email_address"
"aud": "https://api.asperafiles.com/api/v1/oauth2/token",
"nbf":
valid_start_time,
"exp":
token_expiration_time
}

Where:
— “iss” is the client ID that is generated when you register an API client.
— “sub” is the email address of the user who will use the bearer token for authentication.
— “aud” is always “https://api.asperafiles.com/api/v1/oauth2/token”.
— “nbf” is the Unix timestamp when the bearer token becomes valid; for example, 1524616200.
— “exp” is the Unix timestamp when the bearer token expires, for example 1525134600.

For example,
$ echo -n '{"iss":"test","sub":"admin@asperasoft.com","aud":"https://api.asperafiles.com/api/v1/oauth2/token","nbf":1483984874,"exp":1516318468}' | base64 | tr '+' '-' | tr '/' '_' | tr -d '=' eyJpc3MiOiJ0ZXN0Iiwic3ViIjoiYWRtaW5AYXNwZXJhc29mdC5jb20iLCJhdWQiOiJodHRwczovL2FwaS5hc3BlcmFmaWxlcy5jb20vYXBpL3YxL29hdXRoMi90b2tlbiIsIm5iZiI6MTQ4Mzk4NDg3NCwiZXhwIjoxNTE2MzE4NDY4fQ

3. Sign the combined header and payload with the user’s private key and encode the signature by running the following command (in this example, private_key.pem is the user’s private key file):
$ echo -n encoded_header.encoded_payload | openssl dgst -sha256 -sign private_key.pem | base64 | tr '+' '-' | tr '/' '_' | tr -d '='

For example,
$ echo -n eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ0ZXN0Iiwic3ViIjoiYWRtaW5AYXNwZXJhc29mdC5jb20iLCJhdWQiOiJodHRwczovL2FwaS5hc3BlcmFmaWxlcy5jb20vYXBpL3YxL29hdXRoMi90b2tlbiIsIm5iZiI6MTQ4Mzk4NDg3NCwiZXhwIjoxNTE2MzE4NDY4fQ | openssl dgst -sha256 -sign private_key.pem | base64 | tr '+' '-' | tr '/' '_' | tr -d '='io-t_tVHwA_4qGRC6uBXtjAsyxfJsBwSdAxTsocyX6oERUdRKaXFammUCdb6PmSxtaB88I912lpgIK4Wwrb55p7AFrZjKmcmBN5AZJrhPAB-J3d1M_7h8chLZUoFGS6ny5NgInRsk1I_qdTCCe9pUTNpcv7MRErvmgcNTcJqZ21nrFYlQM8DX8rezs1rwH7nDHDzA-9U5E_J9e19v-tRmTJHAxhpeeDrlvgRiS84bW3_2msF9tNSMTjcckGq4XvgLtgc4eMLN4BSLjp7Q9FKZwSxx_Ry-N_U972fo_aHXakstxGxtim8CCGWAkpu1AnoW-zrv0Kk1IXNU4qY-bwX6w

4. Request a bearer token by sending the following request to the Files API:
$ curl -i -u client_id:secret -H "Content-Type: application/x-www-form-urlencoded" -X POST https://api.asperafiles.com/api/v1/oauth2/{org_name}/token -d"assertion=encoded_header.encoded_payload.encoded_signature&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&scope=scope"

The scope can be one of the following:

Scope

Description

user:all

Allows access to Files user features, including creating and modifying packages and files; retrieving node and organization information; and managing contacts. User-scoped tokens do not allow the user to create nodes, manage other users, or manage workspaces.

admin:all

Allows access to Files admin features, including creating nodes, managing workspaces, and adding users to workspaces. Admin-scoped bearer tokens have shorter expirations and require re-authenticating more frequently.

Note: Because the scope of the token affects the function of the Files API endpoints, Aspera recommends that you use user-scoped bearer tokens for user-specific activity, and admin-scoped tokens for admin activity.

For example,

$ curl -i -u 61in8fhrw:zHslLvyJRxzrTrRnskTbl3JYlQAmF17lhvJbES -H “Content-Type: application/x-www-form-urlencoded” -X POST https://api.asperafiles.com/api/v1/oauth2/organization424/token -d”assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ0ZXN0Iiwic3ViIjoiYWRtaW5AYXNwZXJhc29mdC5jb20iLCJhdWQiOiJodHRwczovL2FwaS5hc3BlcmFmaWxlcy5jb20vYXBpL3YxL29hdXRo42Mi90b2tlbiIsIm5iZiI6MTQ4Mzk4NDg3NCwiZXhwIjoxNTE2MzE4NDY4fQ.io-t_tVHwA_4qGRC6uBXtjAsyxfJsBwSdAxTsocyX6oERUdRKaXFammUCdb6PmSxtaB88I912lpgIK4Wwrb55p7AFrZjKmcmBN5AZJrhPAB-J3d1M_7h8chLZUoFGS6ny5NgInRsk1I_qdTCCe9pUTNpcv7MRErvmgcNTcJqZ21nrFYlQM8DX8rezs1rwH7nDHDzA-9U5E_J9e19v-tRmTJHAxhpeeDrlvgRiS84bW3_2msF9tNSMTjcckGq4XvgLtgc4eMLN4BSLjp7Q9FKZwSxx_Ry-N_U972fo_aHXakstxGxtim8CCGWAkpu1AnoW-zrv0Kk1IXNU4qY-bwX6w&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&scope=user%3Aall”

HTTP/1.1 201 Created

{

“access_token”:”eJwdkNuOokAURd/5DF4dQgElFxMflIuIAtqAFzqdDpcSUcSyoFTozL8PPQ8n2VlZ2Ts5PyxtEPkuc3bCiuwftsnuGA35l06SqhoQeuOSoOY7aX8dICgcEDhBC0UwEZQJAPHgUPq/QREUkAqJzMkwyzh4gimX5ILGpZmWKTmEQMpPg12QO8XDZsNOPllhAOPhJPbrLzOdBsuFNwujD3M6ZXB109dCHirLo296RjAmqxFd1LkR39uVG5OHrZ6XzsOOjlgsna19t6o0HgeF61U94yu+BC31fUqKdiOVNJBI5p59Y7spu6KuK/jRi2htBy4Jm9IKZY1/JOpxDbGSvph3V89Sq6eWi1Rt1+4lpGnt6CiPlsg6FJ7m392NuZnLHtEF7Iid7CWxfeGNuo1C5rz33eIBQEgJwn2a2wdI67C9oWB3RbzlXC295AGYz66pEu9pYnvzC32BGswvL4b0wPRETBIM1O6lNry2Q/tqcT0fbqbTdcdTaXQ38KaR7VFYBhtdvUHB4hdPBzXMOyHRFrqJWvHSc/H01wcU87oum3KP9Og6Gq+NEGOyWs2G7/4DxMqeUg==”,

“token_type”:”bearer”,

“expires_in”:3599,

“scope”:”admin:all”

}

Record the value for “access_token”, which is the bearer token that the user can use to authenticate requests to the Files API, and note when the token expires (“expires_in” is reported in seconds).

This Files bearer token can now be used to authenticate requests to the Files API. It cannot be used to authenticate requests to the Node API, including transfers with /ops/transfers; see the following instructions for requesting a Node API bearer token that can be used to authenticate Node API requests to Files nodes.

Using the Files bearer token to create a Node API bearer token

The Files bearer token cannot be used to authenticate requests to the Node API. Instead, you request a Node API bearer token that contains node-specific information.

1. Retrieve the access key that is associated with the Files bearer token and the node URL (the target of your Node API requests) by sending the following request to the Files API:

curl -i -H "Authorization: Bearer token_string" -X GET https://api.asperafiles.com/api/v1/nodes

For example,

$ curl -i -H "Authorization: Bearer eyIwMTgtMDUtMjNUpbmUiLCy" -X GET https://api.asperafiles.com/api/v1/nodes

HTTP/1.1 200 OK

[{"access_key":"hMBQmvNhEILmR42hm904lR22TmdV8-1BA-aslep4L6I",

"capabilities":[

{"name":"sync","value":true},

{"name":"watchfolder","value":true},

{"name":"symbolic_links","value":false},

{"name":"move_file","value":true},

{"name":"move_directory","value":false},

{"name":"filelock","value":true},

{"name":"ssh_fingerprint","value":true}],

"configuration_policy_id":null,

"host":"files-qa-aejd.qa.asperafiles.com",

"id":"1913",

"name":"files-qa-aejd.qa.asperafiles.com",

"path":"/","port":443,

"settings":[

{"name":"content_protection_required","value":false},

{"name":"content_protection_strong_pass_required","value":false},

{"name":"filelock_restriction","value":"none"},

{"name":"ssh_fingerprint","value":"3494mgel4j634543ij"}],

"status":"ok",

"url":"https://files-qa-aejd.qa.asperafiles.com:443/",

"use_ssl":true,

"verify_ssl_certificate":true,

"network_policy_id":null,

"ats_access_key":false,

"ats_storage_type":null,

"ssh_fingerprint":null}]

Record the values for “access_key” and “url”.

2. Request a Node API bearer token by sending the following request to the Files API:

$ curl -i -u client_id:secret -H "Content-Type: application/x-www-form-urlencoded" -X POST https://api.asperafiles.com/api/v1/oauth2/{org_name}/token -d"assertion=encoded_header.encoded_payload.encoded_signature&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&scope=scope"

Important: For the Node API bearer token, the scope must include the access key, as node.access_key.user:all or node.access_key.admin:all.

Scope

Description

node.url-encoded-ak:user:all

Allows access to files, folders, and permissions on the node that is associated with the access key, within the tenant space that is set in the access key.

node.url-encoded-ak:admin:all

Allows administration of the access key and its storage on the node, as well as access to all content in the tenant space.

For example,

$ curl -i -u 61in8fhrw:zHslLvyJRxzrTrRnskTbl3JYlQAmF17lhvJbES -H "Content-Type: application/x-www-form-urlencoded" -X POST https://api.asperafiles.com/api/v1/oauth2/organization424/token -d"assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ0ZXN0Iiwic3ViIjoiYWRtaW5AYXNwZXJhc29mdC5jb20iLCJhdWQiOiJodHRwczovL2FwaS5hc3BlcmFmaWxlcy5jb20vYXBpL3YxL29hdXRoMi90b2tlbiIsIm5iZiI6MTQ4Mzk4NDg3NCwiZXhwIjoxNTE2MzE4NDY4fQ.io-t_tVHwA_4qGRC6uBXtjAsyxfJsBwSdAxTsocyX6oERUdRKaXFammUCdb6PmSxtaB88I912lpgIK4Wwrb55p7AFrZjKmcmBN5AZJrhPAB-J3d1M_7h8chLZUoFGS6ny5NgInRsk1I_qdTCCe9pUTNpcv7MRErvmgcNTcJqZ21nrFYlQM8DX8rezs1rwH7nDHDzA-9U5E_J9e19v-tRmTJHAxhpeeDrlvgRiS84bW3_2msF9tNSMTjcckGq4XvgLtgc4eMLN4BSLjp7Q9FKZwSxx_Ry-N_U972fo_aHXakstxGxtim8CCGWAkpu1AnoW-zrv0Kk1IXNU4qY-bwX6w&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&scope=node.hMBQmvNhEILmR42hm904lR22TmdV8-1BA-aslep4L6I%3Aadmin%3Aall"

HTTP/1.1 201 Created

{

"access_token":"eJwdkNuOokAURd/5DF4dQgElFxMflIuIAtqAFzqdDpcSUcSyoFTozL8PPQ8n2VlZ2Ts5PyxtEPkuc3bCiuwftsnuGA35l06SqhoQeuOSoOY7aX8dICgcEDhBC0UwEZQJAPHgUPq/QREUkAqJzMkwyzh4gimX5ILGpZmWKTmEQMpPg12QO8XDZsNOPllhAOPhJPbrLzOdBsuFNwujD3M6ZXB109dCHirLo296RjAmqxFd1LkR39uVG5OHrZ6XzsOOjlgsna19t6o0HgeF61U94yu+BC31fUqKdiOVNJBI5p59Y7spu6KuK/jRi2htBy4Jm9IKZY1/JOpxDbGSvph3V89Sq6eWi1Rt1+4lpGnt6CiPlsg6FJ7m392NuZnLHtEF7Iid7CWxfeGNuo1C5rz33eIBQEgJwn2a2wdI67C9oWB3RbzlXC295AGYz66pEu9pYnvzC32BGswvL4b0wPRETBIM1O6lNry2Q/tqcT0fbqbTdcdTaXQ38KaR7VFYBhtdvUHB4hdPBzXMOyHRFrqJWvHSc/H01wcU87oum3KP9Og6Gq+NEGOyWs2G7/4DxMqeUg==",

"token_type":"bearer",

"expires_in":899,

"scope":"node.hMBQmvNhEILmR42hm904lR22TmdV8-1BA-aslep4L6I:admin:all"

}

3. To confirm that your Node API bearer token works, run a test Node API request:

curl -i -H "Authorization: Bearer token_string" -H "X-Aspera-AccessKey: access_key" -X GET https://node_url:443/info

For example,

curl -i -H "Authorization: Bearer eJwlUNmOokAAfOczeGVZ6QNtTHxARQdhNByCsNlMWroFlGsAlXGy/75k97GOVFXqW7x3vP3ImTgXMQCaJv4Qu6Ru+IirmvGf2fvSKR/7zDDt0sUwKzUFFy6EfskCIoOlLtOu4A22p+acsjKv5rQoxhA+NHnLuw/aj0lQAURWVBkBH5A5UueIxKPnfv/XSxknyhljmSMNypgzJNPLRZHJmVwoJYTNZnB0121Kq/xF+7yu/g8GaKapo5K29b0ZqU6c/xLhFKpA/P1HWCw8c7vX/aNrLBbCDQSpwl6m8dj2dhHrN2e4ams77g/bw6WM3DVuwZqaEExyPTKqtpJo09xNwPFpEN7s6VDf0tZOk5e/+QJRi9fxEy9X/Om5J0z9Z7qZBk4qxZYF1oS16ip9v9rBbrCRYOJKjTQ37/X7KUBN2qKuPH6V0qMMO/0BNsWrVK0At6cM6Ak0QueEAJ35n3V8GAQpD44opIlxnAVkXXWvJtqOL0MpCTfkERUT4/p4HY4g9g6FxiQ0jQ0nY53EyLkTvHBV+oEjVU09YIvnVmx9nuvd9ES4ubF3albDFJmGO9G3LLF7qZvB2Mpos4zjqwDCDhn7qtdD70m2+Kk7Z/+iMe+tybw0SxzVHrJJi46RM777F7tAth4=" -H "X-Aspera-AccessKey: hMBQmvNhEILmR42hm904lR22TmdV8-1BA-aslep4L6I" -X GET https://files-test.asperafiles.com:443/info

You can now use the bearer token to authorize a Node API transfer request to an Aspera on Cloud node. For instructions, see https://developer.asperasoft.com/web/node/ops-transfers#start-transfer.

Tutorial

This section contains the following:

  • Use case
  • Workflow overview
  • Procedures

Use case

Build a simple app using the IBM Aspera Files API package sending capabilities to test throughput. If you need information on this Files capability, see “Sending” in The Aspera Files API.

Workflow summary

This high-level workflow summarizes the required steps. Details procedures for each step follow this summary.

Workflow Summary part 1: Using an admin-scoped token

You need an admin-scoped authorization token to perform the steps in this table.

Step

Action Summary (see Detailed Procedures below)

Endpoint

1

Have the IBM Aspera Files administrator use the Files GUI to:

· Register your client and give you:

o Client ID.

o Client secret.

· Give you the node ID.

See the Registration and app key section.

2

Obtain an admin-scoped token to send with each API call.

See the Authorization section.

3

Create two users: one to send the package and one to receive it.

· Request requires:

o Admin-scoped Files bearer token.

o User email address.

o User public key.

o Set ‘organization_admin” to “true”.

· Response returns user ID.

POST /users

4

(Optional) If your app users are to be authenticated using JWT, add the two users to a whitelist of users authorized to use your client.

· Request requires:

o Admin-scoped Files bearer token.

o Client ID (see step 1).

o Entity type: ‘user’ or ‘group’

o User ID (see step 3).

POST /client_authorizations

5

Create the workspace.

· Request requires:

o Admin-scoped Files bearer token.

o Workspace name.

o Node ID (see step 1).

· Response returns the workspace ID.

POST /workspaces

6

Add the two users as members to the workspace.

· Request requires:

o Admin-scoped Files bearer token.

o Workspace ID (see step 5)

o User ID (see step 3)

POST /workspace_memberships

Workflow Part 2: Using a user-scoped token

You can perform the steps in this table using a user-scoped token.

Step

Action

Endpoint

7

Obtain a user-scoped token to send with each API call.

See the Authorization section.

8

Create a package and add files and folders to it.

· Request requires:

o User-scoped Files bearer token.

o User ID for each recipient.

o Workspace ID.

· Response returns:

o Package ID.

o Node ID.

o Contents file ID.

POST /packages

9

Retrieve the package to return the node details.

· Request requires:

o User-scoped Files bearer token.

o Package ID (see step 8).

· Response returns:

o Node host name.

o Node access key.

GET /packages/{id}?embed[]=node

10

Note: This step requires a node token: see the Authorization section.

Using the Node API, start the transfer of the package to the node.

· Request requires:

o Node token.

o Node host name.

o Node access key.

· Response returns the transfer ID.

NODE API:

POST /ops/transfers

11

Note: This step requires a node token: see the Authorization section.

Using the Node API, retrieve the status of the transfer from the node.

· Request requires:

o Node token.

o Transfer ID (see step 10).

· Response returns transfer status.

NODE API:

GET /ops/transfers

12

Update the package containing the files to mark it sent.

· Request requires:

o User-scoped Files bearer token.

o Package ID (see step 8).

PUT /packages/{id}

Procedures

Step 1: Register your app with the Files API

This workflow suggests that an Aspera Files administrator use the Aspera Files GUI to register the client and get the client ID and secret. See the Registration and app key section.

However, for reference, sample use of the /clients endpoint follows.

The registration generates the client ID and secret. These values are required in subsequent requests.

Sample request

Request requires a client name.

POST https://api.asperafiles.com/api/v1/clients
{
    "explicit_authorization_required": true,
    "jwt_grant_enabled": true,
    "whitelist_enabled": true,
    "name": "My Files Client",
    "redirect_uris": [
      "https:\/\/FilesClientRedirect.com"
    ],
    "origins": [
      "https:\/\/FilesClientOrigin.com"
    ],
    "admin_node_token_retrieval_enabled": true,
    "public_key": null,
}

Sample response

Response returns the client ID and secret.

{
    "admin_node_token_retrieval_enabled": true,
    "allow_implicit_grant": false,
    "created_at": "2018-02-08T01:46:37.000Z",
    "creator_id": "151",
    "explicit_authorization_required": true,
    "id": "_Wd24ucAw",
    "jwt_grant_enabled": true,
    "name": "My Files Client",
    "organization_id": "4",
    "origins": [
      "https:\/\/FilesClientOrigin.com"
    ],
    "public_key": null,
    "redirect_uris": [
      "https:\/\/FilesClientRedirect.com"
    ],
    "secret": "yHIH3ZNJngz901V4ATSjvTklsseJCxj6gQVs8WVmiGC2K7qA4BPQq7fziTI9HCb6Y-_ML5zN5e_aTIXJ_JiiPI6UHjO67wRu",
    "updated_at": "2018-02-08T01:46:37.000Z",
    "whitelist_enabled": true
}

Step 2: Obtain an admin token

See the Authorization section.

Note that the admin session token expiration settings are not configurable, and are set as follows:

· Inactive session duration: 15 minutes
After 15 minutes of inactivity, Aspera Files automatically logs the user out.

· Login token expiration: 30 minutes
The login token issued to the user expires after 30 minutes, but can be refreshed per the login token refresh duration setting.

· Login token refresh duration: 12 hours
Aspera Files refreshes the login token of an active user for up to 12 hours. After 12 hours, the user must re-authenticate.

Step 3: Create users

Use the /users endpoint to create two users: one to send and one to receive. You must include an email address to create a user. First and last names are optional.

Give both users organization administrator privileges and include a public key (.pem format) for each.

You’ll add these users to the client access whitelist, and later, to the workspace you create.

Sample request

Request requires:

· Aspera Files admin-scoped bearer token.

· User email address

· User public key

· “organization_admin”: “true”

POST https://api.asperafiles.com/api/v1/users

{

“email”: “jane.doe@example.com”,

“first_name”: “Jane”,

“last_name”: “Doe”

“organization_admin”: “true”

“public_key”: “—–BEGIN PUBLIC KEY—– \nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvLhSNC6e7TqzNEoJ\/\/CF\nWU\/3AhmacM60yON2ykN97cpBhxs44W+BREuw79qPmvXttbDunO0j2aPR+PqnZAsN\nypu2pBN4CehAJ8UtIKXLcehd7v5ls23S3FHnTtdOJPljCaoQOvX4\/9cH85sMzbhO\nMpxNjQ7fnuk+Yxxwf1avunNi8HE6i5d9ORzBs6ZS5n\/jgjfe+90PiaHk5LC1FjLa\nZZlwp8Sx+gXCAFPh67SfQYMU5+So26F7c1Q5geiGlmCpuDvl5xGgGnHCAqIWArqF\nzW8PlbjDojAMb2k0Ukpnsm92sdNXQTFpaCqiYDHMxgzJWYVCvzKM6DpU9U2a8AoY\nMwIDAQAB\n—–END PUBLIC KEY—–“

}

Sample response

The response contains the user ID, which you use in both the /client_authorizations call to add a user to the client access whitelist and in the /workspace memberships call to add the user to the workspace you will create.

{

“ats_admin”: false,

“created_at”: “2018-02-17T02:35:58.000Z”,

“deactivated”: false,

“default_workspace_choice”: “last_used”,

“default_workspace_id”: null,

“email”: “jane.doe@example.com”,

“first_name”: “Jane”,

“home_file_id”: null,

“home_node_id”: null,

“id”: “92769”,

“last_login_at”: null,

“last_name”: “Doe”,

“member_of_any_workspace”: false,

“name”: “Jane Doe”,

“organization_admin”: true,

“password_updated_at”: null,

“provisioned”: true,

“public_key”: “—–BEGIN PUBLIC KEY—– \nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvLhSNC6e7TqzNEoJ\/\/CF\nWU\/3AhmacM60yON2ykN97cpBhxs44W+BREuw79qPmvXttbDunO0j2aPR+PqnZAsN\nypu2pBN4CehAJ8UtIKXLcehd7v5ls23S3FHnTtdOJPljCaoQOvX4\/9cH85sMzbhO\nMpxNjQ7fnuk+Yxxwf1avunNi8HE6i5d9ORzBs6ZS5n\/jgjfe+90PiaHk5LC1FjLa\nZZlwp8Sx+gXCAFPh67SfQYMU5+So26F7c1Q5geiGlmCpuDvl5xGgGnHCAqIWArqF\nzW8PlbjDojAMb2k0Ukpnsm92sdNXQTFpaCqiYDHMxgzJWYVCvzKM6DpU9U2a8AoY\nMwIDAQAB\n—–END PUBLIC KEY—–“,

“read_only_home_file_id”: null,

“read_only_home_node_id”: null,

“running_operation_count”: 0,

“stopped_operation_count”: 0,

“support_user”: false,

“updated_at”: “2018-02-17T02:35:58.000Z”,

“saml_configuration_id”: null,

“default_shortlink_name”: “Jane_Doe”

}

Step 4: Add users to the client access whitelist

The default configuration is that all users have authorization to use the client. For greater security, you can control which users are authorized to use your client by creating a whitelist.

Configure which users or groups can access the API using your client, and which type of key each user can submit to retrieve an access token–either a user-specific key or a global key.

Use the /client_authorizations endpoint to configure the authorized users or groups; use the /users endpoint to configure the user key types; use the /clients endpoint to configure the global key.

This request requires:

· Aspera Files admin-scoped bearer token.

· client_id: see Step 1 above. Also available from the /clients endpoint.

· entity_type: indicating whether the entity is a user or group; in this case, valid value is “user”.

· entity_id: the user (or group) ID, available from the /users (or /groups) endpoint.

Sample request

The intended authorization for this client includes a whitelist of two users, one with ID 92769, and one with ID of 251. Each entity to authorize requires a separate request.

POST https://api.asperafiles.com/api/v1/client_authorizations

{

“client_id”: “_Wd24ucAw”,

“entity_type”: “user”,

“entity_id”: “92769”

}

POST https://api.asperafiles.com/api/v1/client_authorizations

{

“client_id”: “_Wd24ucAw”,

“entity_type”: “user”,

“entity_id”: “251”

}

Sample response

201 Created

Step 5: Create a workspace

The workspace is a distinct context in which workspace members can freely share files and send packages. All workspace users of the same type (members; workspace managers) share collaboration settings for that user type. A workspace is a folder on a specific node; the workspace storage is separate from other workspaces.

This request requires:

· Aspera Files admin-scoped bearer token.

· Name for the workspace.

· Node ID, delivered to you by the Files administrator earlier in this flow (see Registration and App Key); also available from the /nodes endpoint.

Sample request

POST https://api.asperafiles.com/api/v1/workspaces

{

“storage_allowed”: true,

“url_shortening_enabled”: true,

“name”: “My New Workspace”,

“description”: “Workspace Description”,

“image_type”: “image\/png”,

“image_data”: “iVBORw0KGgo … /wB\/DRk84ZdwGQAAAABJRU5ErkJggg==”,

“node_id”: “14”,

“invitations_allowed_by_managers”: true,

“invitations_allowed”: false,

“external_package_sending_allowed_by_managers”: true,

“external_package_sending_allowed”: true,

“external_sharing_allowed_by_managers”: true,

“external_sharing_allowed”: true,

“public_links_allowed_by_managers”: true,

“public_links_allowed”: true,

“public_invites_allowed_by_managers”: true,

“public_invites_allowed”: true,

“collaboration_settings_editable_by_managers”: false,

“collaboration_with_emails_allowed”: true,

“collaboration_whitelist_enabled”: false,

“external_package_authentication_required”: false

}

Sample response

The response contains the workspace ID, which you use in the /workspace_memberships call to add the users you created to the workspace.

{

“allow_package_level_expirations”: false,

“collaboration_settings_editable_by_managers”: false,

“collaboration_whitelist_enabled”: false,

“collaboration_with_emails_allowed”: true,

“content_retention_duration”: null,

“created_at”: “2018-02-16T04:30:58.000Z”,

“default_ear_setting”: null,

“delete_package_content_after_download_duration”: null,

“description”: “Workspace Description”,

“draft_expiration_duration”: null,

“effective_default_ear_setting”: false,

“email_footer”: null,

“email_notification_settings”: {

“dropbox_invitation”: true,

“file_shared”: true,

“invitation_to_send_to_me”: true,

“package_contents_deleted”: true,

“package_downloaded”: true,

“package_expired”: true,

“package_failed”: true,

“package_recalled”: true,

“package_received”: true,

“package_resent”: true,

“package_sent”: true,

“package_uploaded”: true

},

“enable_external_email_templates”: false,

“enable_external_notifications”: true,

“event_reporting_uri”: null,

“external_package_authentication_required”: false,

“external_package_sending_allowed_by_managers”: true,

“external_package_sending_allowed”: true,

“external_sharing_allowed_by_managers”: true,

“external_sharing_allowed”: true,

“group_id”: “27676”,

“home_container_file_id”: null,

“id”: “9519”,

“image_type”: “image\/png”,

“image_url”: “https:\/\/api.asperafiles.com\/api\/v1\/user_images\/37792?oh=Gea … XTqTNJ1cBaDjqmw”,

“inherit_email_notification_settings”: true,

“inherit_email_templates”: true,

“invitations_allowed_by_managers”: true,

“invitations_allowed”: false,

“managers_group_id”: “27677”,

“member”: false,

“name”: “My New Workspace”,

“node_id”: “14”,

“personalized_urls_enabled”: false,

“public_invites_allowed_by_managers”: true,

“public_invites_allowed”: true,

“public_links_allowed_by_managers”: true,

“public_links_allowed”: true,

“root_file_id”: null,

“running_operation_count”: 0,

“spool_file_id”: null,

“stopped_operation_count”: 0,

“storage_allowed”: true,

“updated_at”: “2018-02-16T04:30:58.000Z”,

“url_shortening_enabled”: true

}

Step 6: Add users to the workspace

Add the two users you created in step 3 above to the workspace. Make one call for each user to add.

This request requires:

· Aspera Files admin-scoped bearer token.

· Workspace ID

· User ID for each user

Sample request

POST https://api.asperafiles.com/api/v1/workspace_memberships

{

“workspace_id”: “9519”,

“member_type”: “user”,

“member_id”: “92769”,

“manager”: false

}

Sample response

{

“id”: “67961”,

“manager”: false,

“member_id”: “92769”,

“member_type”: “user”,

“running_operation_count”: 1,

“stopped_operation_count”: 0,

“workspace_id”: “9519”

}

Step 7: Obtain a user token

To complete the remaining steps, you need a user-scoped token. See the Authorization section.

Step 8: Create the package

Create the package that will contain the files and folders to transfer from one user to another.

This request requires:

· Aspera Files user-scoped bearer token.

· User ID for each recipient

· Workspace ID

Sample request

Create a package with one file to a recipient (user ID = 411).

POST https://api.asperafiles.com/api/v1/packages

{

“recipients”: [

{

“id”: “411”,

“type”: “user”

}

],

“upload_notification_recipients”: [

],

“download_notification_recipients”: [

],

“bcc_recipients”: [

],

“file_names”: [

“Files_Admin_SharingFolder.mp4”

],

“name”: “New version”,

“workspace_id”: “14”,

“encryption_at_rest”: false,

“delete_package_content_after_download_duration”: null,

“content_retention_duration”: null,

“single_source”: true

}

Sample response

This response returns:

· The package ID.

· Node ID.

· Contents files ID.

{

“active_download_count”: null,

“archived”: false,

“average_rate”: null,

“bcc”: false,

“bcc_recipients”: [

],

“bytes_transferred”: null,

“complete”: false,

“completed_at”: null,

“content_expires_at”: null,

“content_retention_duration”: null,

“contents_file_id”: “965862”,

“created_at”: “2018-06-29T19:31:24.000Z”,

“delete_after_download”: false,

“delete_package_content_after_download_duration”: null,

“deleted”: false,

“deleted_after_download”: false,

“deleted_at”: null,

“deleted_by_admin”: false,

“deleted_by_user_id”: null,

“download_notification_recipients”: [

],

“draft”: true,

“draft_expires_at”: null,

“encryption_at_rest”: false,

“expiration_reason”: null,

“expired”: false,

“expired_at”: null,

“failed”: false,

“failed_download_count”: null,

“file_count”: null,

“file_count_from_disk”: null,

“file_id”: “965861”,

“files_completed”: 0,

“files_expected”: null,

“folders_completed”: null,

“folder_count”: null,

“folders_expected”: null,

“full_download_count”: null,

“has_content”: true,

“id”: “BchIhV7o6Q”,

“metadata”: null,

“name”: “New version”,

“node_id”: “14”,

“note”: null,

“package_sent”: false,

“partial_download_count”: null,

“read”: false,

“recalled_at”: null,

“received”: false,

“sender”: {

“email”: “kchargi@us.ibm.com”,

“id”: “117445”,

“name”: “Katherine Chargin”,

“type”: “user”

},

“sent”: false,

“sent_at”: null,

“single_source”: true,

“size”: null,

“time_remaining”: null,

“transfers_expected”: null,

“updated_at”: “2018-06-29T19:31:24.000Z”,

“upload_notification_recipients”: [

],

“upload_started”: false,

“upload_started_at”: null,

“workspace_id”: “16”,

“recipients”: [

{

“email”: “james@asperasoft.com”,

“id”: “411”,

“name”: “Wilson James”,

“type”: “user”

}

]

}

For reference, following is the entire process of creating a digital package and transferring it.

The process of sending a package comprises multiple steps. You use the POST, GET, and PUT methods of /packages, along with requests to the Connect API or the Node API. This sample flow uses the IBM Aspera Node API for the transfer.

1. Create the package. POST /packages

a. At this point the package is an empty container on the transfer node defined by various parameter as required (name, recipients, etc.).

b. The response to this request includes package_id, node_id, and contents_file_id.

2. Retrieve this package to return the node details.
Use GET /packages/{id}?embed[]=node.
Response includes node host name and access key.

3. Upload files and folders for the package package_id into the file specified by node_id and contents_file_id. POST /ops/transfers (Node API)

a. This request is addressed to the node using the host name and access key obtained in the previous call.

b. This request creates the “Transfer Spec” and returns it in the response.

c. The response includes the xfer_id, which can be used to poll transfer status.

d. For browser-based apps, see the Aspera Connect API at https://developer.asperasoft.com.

e. For standalone apps, see the Aspera Node API at https://developer.asperasoft.com.

4. Update the package to mark it sent; include the number of transfers expected. PUT /packages/{id}

a. Include “sent”: true, “transfers_expected”: X, where X corresponds to the number of transfers required to complete the package; this value depends on the number of discrete source locations of package contents.

b. This finalizes the package and prevents further modification.

c. Package recipients receive the package after it is marked sent and all expected transfers are complete.

Step 9: Retrieve the package

Use the GET method to retrieve the package, using the package ID and embedding the node.

Sample request

This request requires:

· Aspera Files user-scoped bearer token.

· Package ID.

https://api.asperafiles.com/api/v1/packages/BcgXylEb5g?embed[]=node

Sample response

The response contains the node details required for the next request:

· Node host name.

· Node access key.

{

“active_download_count”: null,

“archived”: false,

“average_rate”: 3561.4,

“bcc”: false,

“bcc_recipients”: [],

“bytes_transferred”: 574491,

“complete”: true,

“completed_at”: “2018-06-29T19:05:40.000Z”,

“content_expires_at”: null,

“content_retention_duration”: null,

“contents_file_id”: “965856”,

“created_at”: “2018-06-29T19:04:29.000Z”,

“delete_after_download”: false,

“delete_package_content_after_download_duration”: null,

“deleted”: false,

“deleted_after_download”: false,

“deleted_at”: null,

“deleted_by_admin”: false,

“deleted_by_user_id”: null,

“download_notification_recipients”: [],

“draft”: false,

“draft_expires_at”: null,

“encryption_at_rest”: false,

“expiration_reason”: null,

“expired”: false,

“expired_at”: null,

“failed”: false,

“failed_download_count”: null,

“file_count”: 3,

“file_count_from_disk”: true,

“file_id”: “965855”,

“files_completed”: 3,

“files_expected”: 3,

“folders_completed”: 0,

“folder_count”: 0,

“folders_expected”: 0,

“full_download_count”: null,

“has_content”: true,

“id”: “BcgXylEb5g”,

“metadata”: null,

“name”: “Latest version for you”,

“node_id”: “14”,

“note”: “Please find the next version, ready for your further processing.”,

“package_sent”: true,

“partial_download_count”: null,

“read”: true,

“recalled_at”: null,

“received”: false,

“sender”: {

“email”: “kchargi@us.ibm.com”,

“id”: “117445”,

“name”: “Katherine Chargin”,

“type”: “user”

},

“sent”: true,

“sent_at”: “2018-06-29T19:04:30.000Z”,

“single_source”: true,

“size”: 574491,

“time_remaining”: 0,

“transfers_expected”: 1,

“updated_at”: “2018-06-29T19:05:40.000Z”,

“upload_notification_recipients”: [],

“upload_started”: true,

“upload_started_at”: “2018-06-29T19:05:08.000Z”,

“workspace_id”: “16”,

“recipients”: [

{

“email”: “james@asperasoft.com”,

“id”: “411”,

“name”: “Wilson James”,

“type”: “user”

}

],

“node”: {

“access_key”: “IjKiNTCm76rEjl7YrPwOFpLARZOYONIk8qHZ4wKaqtsA”,

“capabilities”: [

{

“name”: “sync”,

“value”: true

},

{

“name”: “watchfolder”,

“value”: true

},

{

“name”: “symbolic_links”,

“value”: false

},

{

“name”: “move_file”,

“value”: true

},

{

“name”: “move_directory”,

“value”: false

},

{

“name”: “filelock”,

“value”: true

},

{

“name”: “ssh_fingerprint”,

“value”: true

}

],

“configuration_policy_id”: null,

“error_time”: null,

“error_message”: null,

“host”: “files-prod-es-tor03.asperafiles.com”,

“id”: “14”,

“name”: “files-prod-es-tor03.asperafiles.com”,

“path”: “/”,

“port”: 443,

“settings”: [

{

“name”: “content_protection_required”,

“value”: false

},

{

“name”: “content_protection_strong_pass_required”,

“value”: false

},

{

“name”: “filelock_restriction”,

“value”: “none”

},

{

“name”: “ssh_fingerprint”,

“value”: “663fb5d57a8e7cc83c5f2ddf8acbb456”

}

],

“status”: “ok”,

“url”: “https://files-prod-es-tor03.asperafiles.com:443/”,

“use_ssl”: true,

“verify_ssl_certificate”: false,

“network_policy_id”: null,

“ats_access_key”: false,

“ats_storage_type”: null,

“ssh_fingerprint”: null

}

}

Step 10: Initiate the package transfer

Note: This step requires a node token: see the Authorization section.

Use the IBM Aspera Node API endpoint /ops/transfers to transfer the package. See the IBM Aspera Node API documentation.

Moving the files and folders identified in the “file_names” parameter of the /packages call requires one transfer for each source. For example, if the files and folders specified for a package reside on the same source storage, you need one transfer to move them all into the package. If the files and folders reside on two different storage sources, you need two transfers to move them to the package.

This request requires:

· Node token.

· Node URL.

· Node access key.

Sample request

POST https://files-prod-es-tor03.asperafiles.com/ops/transfers

{

“authentication”: “token”,

“cipher”: “aes-128”,

“direction”: “send”,

“remote_user”: “xfer”,

“remote_host”: “files-prod-es-tor03.asperafiles.com”,

“resume”: “sparse_checksum”,

“save-before-overwrite”: true,

“ssh_port”: 33001,

“token”: “Bearer eJwtktmOokAUhu99DG8dp6uoFRMvEFFoFxQR0cmkg4AC0ihbNzqZdx+Wufm\/1Dn\/WapSf\/pl7mcfodcf9SFkGJP+j37u3h9+HUjunv9Tixbh2pQ\/Gc2UKGbHbPOtzx5LyTjpR32t3XiqnvD3wkmLXBo1zUZOHNdN\/OoRZn7+4RR1JwFAPgR0iIAJxRECI4Gfak9ZtoNdRj2IIBkKnOIhhpgPHZ\/BoesDj17OPvMdp3bfs6uThC+nCO9JtzGuo9fsXj7qY94f\/eoT0l5AILBWJNaCQSOQN4AUwy7LmxMTG6BGBCRy1KYE0KEzCkLjABR1wB2aEQjh\/6AdWA0GQKuw1baWCKTxYQzabTBschRj3kFsQdrtGCIdaIe2o0DEFhR0aMoJEngHsQVqyzmvR\/z+2xuPd9p8LZl7QxmPe1qcmyE4aVJhyWoc7rfzxXKwSWwUuZqcKEtVUfe6TpfEenD+SG30lJIinW+vdvneO6oWOaHAMEVweDdn++SZzNx8O99KB5eW5iQxoqLSFe0W2JnLrGc68eOYwW9YeOtedLiXlratyGRTqadNDgfhZKeFti4bh8PL9zwNCLKlrXLxzS8O0q3+V1rqSshwuNyrgATY+WlMU+1NjPfPaG7Emuzkr+wQyufBYL47XiYroZR3yjqIQrZZ2NnRQWhl+teeM7WD4rIzEUYXetnS7UZa7OaBTV6reHeTFRt\/VqWl6+eLngVqJgPqrNhUxm5lKL0nLqbLwDouTZicPJQaOrqvMn62QGrO9GKGv4K36GIQ9Vq\/7j\/bVeKW”,

“tags”: {

“aspera”: {

“app”: “files”,

“node”: {

“access_key”: “IjKiNTCm76rEjl7YrPwOFpLARZOYONIk8qHZ4wKaqtsA”,

“file_id”: “814772”

},

“usage_id”: “aspera.files.workspace.16”,

“files”: {

“package_id”: “BchIhV7o6Q”,

“package_name”: “New version”,

“package_recipients”: [

{

“email”: “james@asperasoft.com”,

“id”: “411”,

“name”: “Wilson James”,

“type”: “user”

}

],

“organization_id”: “4”,

“package_operation”: “upload”,

“files_transfer_action”: “upload_package”,

“parentCwd”: “14:965862”,

“start_spec”: {

“delete_source”: false,

“destination_root_id”: “965862”,

“direction”: “send”,

“remote_node_id”: “14”,

“remote_user”: “xfer”,

“source_node_id”: “14”,

“source_root_id”: “814772”,

“paths”: [

{

“source”: “\/Atest\/Files_Admin_SharingFolder.mp4”

}

],

“transfer_name”: “Files_Admin_SharingFolder.mp4”,

“package_id”: “BchIhV7o6Q”,

“package_operation”: “upload”

},

“transfer_name”: “Files_Admin_SharingFolder.mp4”

}

}

},

“paths”: [

{

“source”: “Files_Admin_SharingFolder.mp4”,

“destination”: “Files_Admin_SharingFolder.mp4”

}

],

“content_protection_password”: null,

“transfer_name”: “Files_Admin_SharingFolder.mp4”,

“delete_source”: false,

“destination_root_id”: “965862”,

“remote_access_key”: “IjKiNTCm76rEjl7YrPwOFpLARZOYONIk8qHZ4wKaqtsA”,

“source_root_id”: “814772”

}

Sample response

Returns the transfer ID.

{

“id”: “25ed1c0b-99db-469b-ae67-93eb800f4cb8”,

“title”: null,

“tags”: {

“aspera”: {

“xfer_id”: “25ed1c0b-99db-469b-ae67-93eb800f4cb8”,

“xfer_retry”: 15,

“app”: “files”,

“node”: {

“access_key”: “eudemo”,

“file_id”: “9”

},

“usage_id”: “aspera.files.workspace.16”,

“files”: {

“node_id”: “14”,

“created_at”: 1530309041280,

“access_id”: “117445”,

“user_name”: “Katherine Chargin”,

“workspace_id”: “16”,

“workspace_name”: “Engineering”,

“organization_id”: “4”,

“files_transfer_action”: “upload_file”,

“parentCwd”: “5560:9”,

“start_spec”: {

“delete_source”: false,

“destination_root_id”: “9”,

“direction”: “send”,

“remote_node_id”: “5560”,

“remote_user”: “xfer”,

“source_node_id”: “14”,

“source_root_id”: “814772”,

“paths”: [

{

“source”: “Files_Admin_SharingFolder.mp4”

}

],

“transfer_name”: “Files_Admin_SharingFolder.mp4”

},

“transfer_name”: “Files_Admin_SharingFolder.mp4”

}

}

},

“token”: “Bearer eJwtkEmTokAQhe\/+DK6MQ61QGuGhodVubcClXWBioqOkEBFlVxsn5r8Py1zeF5X5MvNF\/ZFuhZ9\/hUIaShBqhFDph1R4SerXhTgR\/k\/\/JvxrMmxsQ3651G3\/Ow1zv\/jiZe1BALI+UPsYfCI4JIMhoG7tud3alfjgkyOgrO8J3+\/X21mfaeqxjyBWj74GPM\/XaneSBzwOn7wMk7jLQupqkCe3tH4W0vCXRGkbDVFYKx7UQkAjkDWAKoFdlzUvbdAAN4LwgOG2hUCHzohQ4wAq7kA6NCcwJv+hdmgSagC0ClttZymijY8Q0KYhsOmphLAOgxa0Tadh2kHt0G5EdNBCBR2acYoR6zBogdtxxuoTv\/\/2RqP1+9R6+dysxqNR7xTmj\/mk2gOlGsf3ZPuKiEFMzC17TGaJ5ViGbM13NDVsTfCX0I6MW3ni5xfLvKCed1EmMQue5aripu4vLwfBAOHPcJHnm0w+Vx9gr1\/17VFWsU2uyj1SA+DsK4RF3tusTsnVerrLuEy497GezyIz3ofrdSGEvdrPuXtyCHhEUZVNLQwtN9vuAhrt4MLWe8ccls5hprlJ7MlCnqazXN+O9fNTgRWfKWvgJItIh5pjmlmsWpPTKXNRsIm5uVz1pkDe38uMfntpYbwxlr7fK0W5b\/hl6rhKJPB6t7Oc+LN4BofSsA7y5GBWq1gvCm\/SE4ubmB5Xsm049sRnWQQPb8FZn6Yufyxf83cQC88RD5I96t\/9B6mn2Nk=”,

“cookie”: null,

“direction”: “send”,

“remote_host”: “eudemo.asperademo.com”,

“remote_user”: “xfer”,

“remote_access_key”: “eudemo”,

“source_root_id”: “814772”,

“destination_root_id”: “9”,

“fasp_port”: 33001,

“ssh_port”: 33001,

“rate_policy”: “fair”,

“symlink_policy”: “”,

“target_rate_kbps”: -1,

“cipher”: “aes-128”,

“content_protection”: null,

“content_protection_password”: null,

“overwrite”: “diff”,

“retry_duration”: “”,

“create_dir”: false,

“precalculate_job_size”: false,

“delete_source”: false,

“remove_after_transfer”: false,

“remove_empty_directories”: false,

“multi_session”: 1,

“multi_session_threshold”: null,

“delete_before_transfer”: false,

“preserve_access_time”: false,

“preserve_modification_time”: false,

“preserve_creation_time”: false,

“use_ascp4”: false

}

Step 11: Retrieve transfer status

Note: This step requires a node token: see the Authorization section.

When the transfer is complete, you can mark the package sent.

Sample request

This request requires:

· Node token.

· Transfer ID.

GET https://files-prod-es-tor03.asperafiles.com/ops/transfers/25ed1c0b-99db-469b-ae67-93eb800f4cb8

Sample response

Returns transfer status, which must be ‘completed’.

{

“id”: “25ed1c0b-99db-469b-ae67-93eb800f4cb8”,

“status”: “completed”,

“start_spec”: {

“source_paths”: [

“\/Files_Admin_SharingFolder.mp4”

],

“destination_path”: “\/”,

“tags”: {

“aspera”: {

“xfer_id”: “25ed1c0b-99db-469b-ae67-93eb800f4cb8”,

“xfer_retry”: 15,

“app”: “files”,

“node”: {

“access_key”: “eudemo”,

“file_id”: “9”

},

“usage_id”: “aspera.files.workspace.16”,

“files”: {

“node_id”: “14”,

“created_at”: 1530309041280,

“access_id”: “117445”,

“user_name”: “Katherine Chargin”,

“workspace_id”: “16”,

“workspace_name”: “Engineering”,

“organization_id”: “4”,

“files_transfer_action”: “upload_file”,

“parentCwd”: “5560:9”,

“start_spec”: {

“delete_source”: false,

“destination_root_id”: “9”,

“direction”: “send”,

“remote_node_id”: “5560”,

“remote_user”: “xfer”,

“source_node_id”: “14”,

“source_root_id”: “814772”,

“paths”: [

{

“source”: “Files_Admin_SharingFolder.mp4”

}

],

“transfer_name”: “Files_Admin_SharingFolder.mp4”

},

“transfer_name”: “Files_Admin_SharingFolder.mp4”

}

}

},

:

(content elided)

:

“sessions”: [

{

:

(content elided)

:

}

],

“bytes_transferred”: 35527508,

“bytes_written”: 35527508,

“bytes_lost”: 0,

“avg_rate_kbps”: 35162.13,

“files_completed”: 1,

“directories_completed”: 0,

“start_time_usec”: 1.530309043e+15,

“end_time_usec”: 1.5303090510831e+15,

“elapsed_usec”: 8083130,

“precalc”: {

:

(content elided)

:

},

“error_code”: 0,

“error_desc”: “”,

“files”: [

{

“id”: “32326750-95e669d2-f56a7083-bf5b1318-7f15”,

“path”: “\/workspaces\/16\/home\/katherine@asperasoft.com (151)\/Atest\/Files_Admin_SharingFolder.mp4”,

“start_time_usec”: 1.530309043e+15,

“elapsed_usec”: 7810085,

“end_time_usec”: 1.5303090508101e+15,

“status”: “completed”,

“error_code”: 0,

“error_desc”: “No error”,

“size”: 35527508,

“type”: “file”,

“checksum_type”: “none”,

“checksum”: “”,

“start_byte”: 0,

“bytes_written”: 35527508,

“session_id”: “9adf87d7-69f7-4f4a-93fa-6545c66c8242”

}

]

}

Step 12: Update the package

Use the PUT method to mark the package “sent=true”, including the proper number of transfers in the “transfers_expected” field (one for each source), after the transfers have completed. This triggers any configured notifications to senders and recipients.

Sample request

PUT https://api.ibmaspera.com/api/v1/packages/BchIhV7o6Q

{

“sent”: true,

“read”: true,

“transfers_expected”: 1

}

Sample response

204 No Content