A user who is a member of a workspace has full access to a home folder within the workspace. The user can upload files into, download files from, and share files with other users from the home folder. In addition, files from received packages can be copied into the home folder.

Home Folder Discovery

In order to access the user's home folder, the node_id and file_id of the home folder need to be obtained first. GET /self will return information about the user, including information about the user's default workspace and home folder within that workspace.

GET /self?embed%5B%5D=default_workspace
200 OK
{
  "created_at":"2016-01-15T00:02:01.000Z",
  "deactivated":false,
  "default_workspace_choice":"last_used",
  "default_workspace_id":"1",
  "email":"mreynolds@mammothstudios.com",
  "first_name":"Matthew",
  "home_file_id":"129",
  "home_node_id":"1",
  "id":"15",
  "last_login_at":"2016-01-18T17:31:08.000Z",
  "last_name":"Reynolds",
  "name":"Matthew Reynolds",
  "organization_admin":false,
  "running_operation_count":0,
  "stopped_operation_count":1,
  "updated_at":"2016-01-18T17:30:57.000Z",
  "default_workspace":{
    "can_invite_by_email":true,
    "created_at":"2016-01-04T14:41:11.000Z",
    "group_id":"1",
    "home_file_id":"129",
    "home_node_id":"1",
    "id":"1",
    "image_data":null,
    "image_type":null,
    "invitations_allowed":true,
    "invited_by_id":"4",
    "manager":false,
    "member":true,
    "name":"Mammoth",
    "running_operation_count":0,
    "stopped_operation_count":1,
    "updated_at":"2016-01-04T14:41:11.000Z",
    "user_id":"15"
  }
}

Note that the embed[]=default_workspace parameter causes information about the user's default workspace to be embedded within the response, eliminating the need to make an additional call to get information about the workspace. If the user belongs to multiple workspaces, information about home folders in other workspaces can be retrieved with a call to GET /workspaces.

Given a node_id and file_id, it is possible to browse the user's home folder. Since the folder exists on a node, information on the node needs to be retrieved first.

GET /nodes/1
200 OK
{
  "access_key":"ZDJXAH-yfXRxrRqCRZsVLCfRBmmZPeq7L8JNyn8ZqVgA",
  "host":"api.f4.vm",
  "id":"1",
  "name":"api.f4.vm",
  "path":"/",
  "port":443,
  "status":"ok",
  "url":"https://api.f4.vm/",
  "use_ssl":true,
  "verify_ssl_certificate":false
}

Now, a bearer token granting access to the node needs to be obtained (with POST /oauth2/{ORGANIZATION}/token).

POST /oauth2/mammoth/token
{
  "client_id":"f4.com",
  "grant_type":"access_token",
  "scope":"node.ZDJXAH-yfXRxrRqCRZsVLCfRBmmZPeq7L8JNyn8ZqVgA:user:all"
}
201 Created
{
  "access_token":"eJwV0EmPokAABeA7P4MrY1sisiUeWIQWWRoQRCadDmBRLiwFyNad+e9jH1/y8r3k/ZB9B9uv24UUSZoj/5BdVmP4ClV9gW+xakTS+2LOI29qvUbx4i40ldyTyzL+gA1n8oY9V3zchEgSfyExKYoXAid8a2H3lTx/WbBiF2C1oDfHFSeuVyLg41cHtXWPX8MdKf4lV+TnP2K79fe6LR0Db7fdEgVkkw8kUNTS39cXn0qu4/U8IEOerJnqUouq9lzhJRw4ZdPNmRHsbjojhLuI2hfErpZilCzr52SVLK4UjQ3DnaYF0d04KpL9XC+Zcj005jQhTJuOivy6eqLqetCVmmgaDtSTmTcn1UTuBbZJ6Zt0rsuBJ1TV/ZDqVn9u+G9VTd+HoktGu1N2mAUHTHOEnPQAw2DeaEcr19XepQ5KZgteWAana2XkKKtRge32u6dld8SuDrCPo2b21XVKOLlhW/yZTft+jp3xyvcMQ3GnOe8Gx7kJ7sM1xwcz3xGsWYMJ+2CE2V22ZmGIEyKbJQ2qIMwoqZefytGKUiBzjlZsVDSC4SQNQh3wRiyj17v/AdnrpBA=",
  "token_type":"bearer",
  "expires_in":603011.369658507,
  "scope":"node.ZDJXAH-yfXRxrRqCRZsVLCfRBmmZPeq7L8JNyn8ZqVgA:user:all"
}

Note that scope in the request is constructed from the node's access key.

The returned access_token can now be used to browse the home folder on the node (header "Authorization: Bearer THE_ACCESS_TOKEN"). In addition to the bearer token, the access key must also be sent in an X-Aspera-AccessKey header.

GET /files/129
Host: api.f4.vm
X-Aspera-AccessKey: ZDJXAH-yfXRxrRqCRZsVLCfRBmmZPeq7L8JNyn8ZqVgA
200 OK
{
  "id" : "129",
  "name" : "mreynolds@mammothstudios.com (15)",
  "type" : "folder",
  "modified_time" : "2016-01-18T18:00:46Z",
  "access_level" : "edit",
  "permission_count" : 1,
  "recursive_folder_count" : 0,
  "recursive_link_count" : 0,
  "recursive_file_count" : 1,
  "recursive_size" : 758,
  "recursive_counts_last_updated_at" : "2016-01-18T18:00:17Z"
}
GET /files/129/files
Host: api.f4.vm
X-Aspera-AccessKey: ZDJXAH-yfXRxrRqCRZsVLCfRBmmZPeq7L8JNyn8ZqVgA
200 OK
[
  {
    "id" : "131",
    "name" : "New Releases",
    "type" : "folder",
    "modified_time" : "2016-01-18T18:00:46Z",
    "access_level" : "edit",
    "permission_count" : 0,
    "recursive_folder_count" : null,
    "recursive_link_count" : null,
    "recursive_file_count" : null,
    "recursive_size" : null,
    "recursive_counts_last_updated_at" : null
  },
  {
    "id" : "130",
    "name" : "info.txt",
    "size" : 758,
    "content_type" : "text/plain",
    "type" : "file",
    "modified_time" : "2016-01-18T18:00:17Z",
    "access_level" : "edit",
    "permission_count" : 0
  }
]

Content can be uploaded to or downloaded from any location within the user's home folder hierarchy. To do so, any of Aspera's transfer APIs can be used. As an example, here is how to use the Connect JavaScript API to upload a file at /tmp/info.txt into the "New Releases" folder shown above.

First, include the Aspera Connect JavaScript SDK in your HTML:

<script src="//d3gcli72yxqn2z.cloudfront.net/connect/v4/asperaweb-4.min.js" />

Then, in JavaScript, instantiate a new AW4.Connect object. Note that Connect 3.6 or higher is required to work with Aspera Files.

var connect = new AW4.Connect({minVersion: "3.6.0});
connect.addEventListener(AW4.Connect.EVENT.STATUS, function() {
  var status = connect.getStatus();
  if (status == AW4.Connect.STATUS.RUNNING) {
    // Connect is ready, continue
    startUpload();
  } else if (status == AW4.Connect.STATUS.FAILED) {
    // Connect initialization has failed, handle the error
    ...
  }
});
connect.initSession();

Once Connect is successfully loaded, create a transfer spec and use it to initiate the transfer:

function startUpload() {
  var transferSpec = {
    authentication: "token",
    direction: "send",
    paths: [
      {
        source: "/tmp/info.txt"
      }
    ],
    remote_user: "xfer",
    remote_host: "api.f4.vm", // from GET /nodes/1
    resume: "sparse_checksum",
    ssh_port: 33001,
    tags: {
      aspera: {
        node: {
          file_id: "131", // file_id of "New Releases" folder
          access_key: "ZDJXAH-yfXRxrRqCRZsVLCfRBmmZPeq7L8JNyn8ZqVgA" // from GET /nodes/1
        },
        files: {
          created_at: new Date().getTime(),
          access_id: "15", // user id from GET /self
          user_name: "Matthew Reynolds", // user name from GET /self
          workspace_id: "1", // workspace id from GET /self
          workspace_name: "Mammoth",
          files_transfer_action: "upload_file"
        },
        usage_id: "aspera.files.workspace.1" // trailing number is workspace id
      }
    },
    token: "Bearer eJwV0EmPokAABeA7P4MrY1sisiUeWIQWWRoQRCadDmBRLiwFyNad+e9jH1/y8r3k/ZB9B9uv24UUSZoj/5BdVmP4ClV9gW+xakTS+2LOI29qvUbx4i40ldyTyzL+gA1n8oY9V3zchEgSfyExKYoXAid8a2H3lTx/WbBiF2C1oDfHFSeuVyLg41cHtXWPX8MdKf4lV+TnP2K79fe6LR0Db7fdEgVkkw8kUNTS39cXn0qu4/U8IEOerJnqUouq9lzhJRw4ZdPNmRHsbjojhLuI2hfErpZilCzr52SVLK4UjQ3DnaYF0d04KpL9XC+Zcj005jQhTJuOivy6eqLqetCVmmgaDtSTmTcn1UTuBbZJ6Zt0rsuBJ1TV/ZDqVn9u+G9VTd+HoktGu1N2mAUHTHOEnPQAw2DeaEcr19XepQ5KZgteWAana2XkKKtRge32u6dld8SuDrCPo2b21XVKOLlhW/yZTft+jp3xyvcMQ3GnOe8Gx7kJ7sM1xwcz3xGsWYMJ+2CE2V22ZmGIEyKbJQ2qIMwoqZefytGKUiBzjlZsVDSC4SQNQh3wRiyj17v/AdnrpBA=" // node token obtained previously
  };

  var connectSettings = {
    allow_dialogs: false,
    app_id: "aspera_15", // trailing number is user id
  };

  connect.startTransfer(transferSpec, connectSettings);
}

Downloading a file from a folder is similar. Here is how to download the info.txt that was just uploaded:

function startDownload() {
  var transferSpec = {
    authentication: "token",
    direction: "receive",
    paths: [
      {
        source: "info.txt"
      }
    ],
    remote_user: "xfer",
    remote_host: "api.f4.vm", // from GET /nodes/1
    resume: "sparse_checksum",
    ssh_port: 33001,
    tags: {
      aspera: {
        node: {
          file_id: "131", // file_id of "New Releases" folder
          access_key: "ZDJXAH-yfXRxrRqCRZsVLCfRBmmZPeq7L8JNyn8ZqVgA" // from GET /nodes/1
        },
        files: {
          file_name: "info.txt",
          file_type: "file",
          created_at: new Date().getTime(),
          access_id: "15", // user id from GET /self
          user_name: "Matthew Reynolds", // user name from GET /self
          node_id: "1",
          workspace_id: "1", // workspace id from GET /self
          workspace_name: "Mammoth",
          files_transfer_action: "download_file"
        },
        usage_id: "aspera.files.workspace.1" // trailing number is workspace id
      }
    },
    token: "Bearer eJwV0EmPokAABeA7P4MrY1sisiUeWIQWWRoQRCadDmBRLiwFyNad+e9jH1/y8r3k/ZB9B9uv24UUSZoj/5BdVmP4ClV9gW+xakTS+2LOI29qvUbx4i40ldyTyzL+gA1n8oY9V3zchEgSfyExKYoXAid8a2H3lTx/WbBiF2C1oDfHFSeuVyLg41cHtXWPX8MdKf4lV+TnP2K79fe6LR0Db7fdEgVkkw8kUNTS39cXn0qu4/U8IEOerJnqUouq9lzhJRw4ZdPNmRHsbjojhLuI2hfErpZilCzr52SVLK4UjQ3DnaYF0d04KpL9XC+Zcj005jQhTJuOivy6eqLqetCVmmgaDtSTmTcn1UTuBbZJ6Zt0rsuBJ1TV/ZDqVn9u+G9VTd+HoktGu1N2mAUHTHOEnPQAw2DeaEcr19XepQ5KZgteWAana2XkKKtRge32u6dld8SuDrCPo2b21XVKOLlhW/yZTft+jp3xyvcMQ3GnOe8Gx7kJ7sM1xwcz3xGsWYMJ+2CE2V22ZmGIEyKbJQ2qIMwoqZefytGKUiBzjlZsVDSC4SQNQh3wRiyj17v/AdnrpBA=" // node token obtained previously
  };

  var connectSettings = {
    allow_dialogs: false,
    app_id: "aspera_15", // trailing number is user id
  };

  connect.startTransfer(transferSpec, connectSettings);
}

For additional details, please refer to the Connect JavaScript API documentation

In order to share a folder with another user or group, the recipient's ID needs to be known first. This can be found by querying the /contacts endpoint.

GET /contacts?current_workspace_id=1&q=elsa
200 OK
[
  {
    "email":"esalazar@mammothstudios.com",
    "member_of_current_workspace":true,
    "name":"Elsa Salazar",
    "source_id":"16",
    "source_type":"user"
  }
]

A permission must be created on the node granting access to that user or group. The Files server will notice the creation of the permission and perform housekeeping such as displaying the shared item in the recipient's home folder and sending out notification emails. As with any other node operation, the access key needs to be included in a request header.

POST /permissions?file_id=131
Host: api.f4.vm
X-Aspera-AccessKey: ZDJXAH-yfXRxrRqCRZsVLCfRBmmZPeq7L8JNyn8ZqVgA
{
  "access_level": "view",
  "access_id": "16",
  "access_type": "user",
  "file_id": "131",
  "tags": {
    "aspera": {
      "files": {
        "workspace": {
          "id": "1",
          "share_as": "New Releases",
          "shared_by_user_id": "15"
        }
      }
    }
  }
}

In order for Files to properly handle the permission creation, the permission needs to be tagged with the workspace ID, the name the folder should by shared as, and the user ID of the sharing user. In this example, access_level is set to "view", which gives the recipient read-only access. Setting it to "edit" will allow the recipient to modify the content within the folder.

For additional file operations, please see the node API documentation.

Video player

Video

×

Reset your Password Password resets are handled on the Support Site

×