Security Architecture

Node API supports four types of authentication:

  • Transfer user - System user who has been set up with a docroot or docroot restriction
  • Node users - User with HTTP basic authentication and a username and secret* (multiple transfer users can be assigned to the same node user)
  • Access keys - HTTP basic authentication and an access key and secret
  • Bearer token - Access key and bearer token used together

*Note: Secret is synonymous with password.

The following is an explanation of how these types of authentication function in the Node API.

Types of Users

  • Transfer User - Transfer users can SSH into the server and are granted access to one or more attached storage elements. They are not Node users and cannot make Node API calls. They can create Node user accounts. They authenticate FASP transfers with a username and secret, or a username and private key.
  • Node User - A node user cannot SSH into the machine, but they have the same access to storage as the associated transfer user. Node users can authorize access to their authorized storage for other node users by creating access keys.
  • Access Key User - An access key user is a node user with an access key that grants access to a restricted area of storage (basic authentication). Access key users can authorize restricted access to their storage for other node users by creating bearer tokens.
  • Bearer Token User - A bearer token user is an access key user with a bearer token that grants restricted access to the storage authorized by the access key.

Node user and access key basic authentication can be used within an application that serves as the broker for front-end clients and applications. In this case, the “secret” used for authentication is not exposed to the outside world. Some application architectures don’t use a broker layer, which allows clients and third-party applications to directly interact with the Aspera servers or clusters. This kind of setup is well-protected by bearer token authentication, because this method does not expose the secret.

Assigning a Node User to a Transfer User

Now that you have your server running with the Node API, you need to create a user who can access files under the system user.

Preliminary Step: Confirm that a document root path has been defined either globally or locally for the system user by examining the <file_system> section of your aspera.conf configuration file. You should have something similar to the section below; add this section to the file if it does not already exist. For more information refer to the aspera.conf reference.


After setting the user's docroot, be sure to restart the Node Service, running the command below with root privileges.

# sudo /etc/init.d/asperanoded restart

Set up the node user by creating a node username and associating it with the system user (in the example below, the system user is xfer. Different nodes may use different Node API username/password pairs.

  1. Run the following command with root or administrator permissions:
    # /opt/aspera/bin/asnodeadmin -a -u node_user -p node_user_password -x xfer

    For example, you can create a new Node User with username nuser-001, password !472830x4n, and transfer user aspera by running the following:

    # asnodeadmin -a -u nuser-001 -p !472830x4n -x aspera

    Note that because the command was run inside the /opt/aspera/bin/ directory, it was not necessary to prepend /opt/aspera/bin/ to the asnodeadmin command.

  2. List the node usernames to confirm that your command was successful.
    # # /opt/aspera/bin/asnodeadmin -1
  3. To verify that your user was created successfully and that they are able to connect and perform operations, rrun the following test commands.  The first operation will return information about the system.  The second /file/browse operation will return a file list of the server.  Be sure to use the proper server address that your server uses and the username and password you just defined.
    curl -u testnodeuser:testpasswd -k -u testnodeuser:testpasswd -k -d '{"path":"/"}'

The asnodeadmin Tool

The asnodeadmin utility in Aspera Connect Server (asnodeadmin.exe for Windows) offers an easy command line tool for managing Node Users. To run this program open a command line prompt and execute the commands in the examples below. be sure to replace the values with the value that you wish to use. If you are not running asnodeadmin inside the /opt/aspera/bin/ directory, you must prepend /opt/aspera/bin/ to the asnodeadmin command.

Note: You must run asnodeadmin as root.

The following commands are supported for managing Node users:

  • Change Password: asnodeadmin -m -u usr1 -x aspera -p new_password
  • List Node Users: asnodeadmin -l
  • Delete Node User: asnodeadmin -d -u node_user

Access Keys and Bearer Tokens

Access keys and bearer tokens are designed for multi-tenancy authorization control in the RESTful Node API. Access keys enable tenant-level access control over a given storage, while bearer tokens specify user or group permissions within the storage path of the access key.

Storage Authorization Options:

  • Docroot set on the server (server-side storage credentials) - The transfer user has a docroot set on the server in aspera.conf and access is authenticated by using SSH credentials (passwords or keys). The docroot can be set as a local file path or as a URI to local or object storage. The client transfers files to "/" or subdirectories of "/", and "/" is relative to the docroot.
  • Restriction set on the server (client-side storage credentials) - The transfer user has a restriction set on the server in aspera.conf and access is authenticated by SSH credentials (passwords or keys). The restriction is a URI path, such as file:////* for local storage or s3://* for AWS S3, that limits the files a client who has their own storage credentials is allowed to access for browsing and transfers. The client specifies the full URI, including their storage credentials for object storage, as the transfer destination (for uploads) or source (for downloads).
  • Access Keys - The transfer user has a restriction set on the server in aspera.conf and the transfer is authenticated using basic auth or bearer token. Access keys contain a storage specification that sets the storage path to which the transfer user has access, such as an S3 bucket or subdirectory. The client transfers files to "/" or subdirectories of "/", and "/" is relative to the storage path set in the access key. The provisioner (a server admin) creates access keys using a REST API.

Node API Access Control Diagram

Which Authorization Method to Use

When using multi-tenancy architecture with the RESTful API, follow these guidelines:

  • If the client application interacts directly with the Node API, use bearer tokens.
  • If the client application interacts with the Node API through a server application broker, use access keys.

No Docroot (Client Side Storage Credentials)

Setup: Set restrictions in the <restrictions> section of the aspera.conf configuration file for a transfer user. For example:


You will also need to create a system user and a public and private key pair. For details, see the section, "Access Keys - Server Setup" below.

Transfers: You can authenticate using the system user and password or private key for that user. Specify the destination for uploads or source for downloads as a full 's3' URI including the credentials. For example:

ascp --mode send --host localhost --user xfer -i ~/.ssh/id_rsa friday01 s3://

No Docroot (FASPStream Server)

Setup: Set access restrictions in the <restrictions> section of the aspera.conf configuration file for a streams user. For example:


You can set restriction values other than "*" for the entry above, for example:

  • By protocol: upd://* or tcp://*
  • By hostname: udp://hostname*
  • By a specific port: udp://hostname:5000*

Authentication: FASPStream uses access key authentication. See Access Keys - Server Setup below.

Access Keys - Server Setup

I. Make a private/public key pair:

openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096
openssl rsa -pubout -in private_key.pem -out public_key.pem

II. Set up the Aspera server (Node API).

Create the xfer user and setup for token auth, set up a file system restriction for the user xfer, and create the node user's SSL certificate.

  1. Make a system user (user_name in the example) without a password:
    useradd -m xfer
  2. Copy the file /opt/aspera/var/ to the user’s authorized_keys file, /home/user_name/.ssh/authorized_keys
  3. Set the login shell to /bin/aspshell
    asconfigurator -x "set_user_data;user_name;file_restriction,\s3://*"
  4. Create the node user (the owner’s or provisioner’s credentials)
    /opt/aspera/bin/asnodeadmin -a -u nodeowner -p secret -x user_name
III. Provisioning: Make access key and set access key token_verification_key (your public key). Example commands are below.
  1. List access keys:
    curl -ki -u nodeowner:secret https://localhost:9092/access_keys
  2. Make a new access key using a file (in the below example, ak.json)
    curl -ki -u nodeowner:secret https://localhost:9092/access_keys  -d @ak.json

    Here is an ak.json file example:
    "secret" : "secret",
    "storage" : {
    	"type" : "aws_s3",
    	"path" : "/",
    	"endpoint" : "",
    	"bucket" : "aspera-demo",
    	"storage_class" : "STANDARD",
    	"server_side_encryption" : null,
    	"credentials" : {
    		"access_key_id" : "777AJPRW777BX7QTQKHQ",
    		"secret_access_key" : "UAuFAW4SM7UahCZAqU1vZH4lgur"

    The access key returned is the following:


  3. To set the public key, make the file ak-token-verif.json and JSON encode the public key.

    Here's an example of ak-token-verif.json:

        "token_verification_key" : JSON-ENCODED-PUBLIC-KEY
  4. Set the public key for the access key with the following command:
    curl -u nodeowner:secret -ki https://localhost:9092/access_keys/nEKTszy5gs9yFlZOnfc4dyzrnwKtj2NH9SIZOkHNmFAA  -X PUT -d @ak-token-verif.json

Upload Using Access Keys and Basic Auth

Create Basic Auth Token: Use basic CREDS format where CREDS is a base64 version of the string access_key:secret. An example of this is seen below:

echo -n nEKTszy5gs9yFlZOnfc4dyzrnwKtj2NH9SIZOkHNmFAA:secret | base64export ASPERA_SCP_TOKEN="Basic bkVLVHN6eTVnczl5RmxaT25mYzRkeXpybndLdGoyTkg5U0laT2tITm1GQUE6c2VjcmV0"

Upload File: You can upload a file to the top of the access key storage using the command seen below; use file_id:1 to indicate the top of the access key storage.

ascp --tags='{"aspera":{"node":{"access_key":"nEKTszy5gs9yFlZOnfc4dyzrnwKtj2NH9SIZOkHNmFAA", "file_id":"1"}}}' \
--mode=send --host= --user=user_name -i /opt/aspera/var/aspera_tokenauth_id_rsa -d  testfile03  /

Uploading to subdirectory: You can upload to a subdirectory by uploading using a file_id of an existing directory or by uploading to file_id:1 with a folder for location. For example:

ascp --tags='{"aspera":{"node":{"access_key":"nEKTszy5gs9yFlZOnfc4dyzrnwKtj2NH9SIZOkHNmFAA", "file_id":"1"}}}' \
--mode=send --host= --user=user_name -i /opt/aspera/var/aspera_tokenauth_id_rsa  -d  testfile03  /tmp

List content: You can use the example below to list the contents of the access key storage.

curl -is -u nEKTszy5gs9yFlZOnfc4dyzrnwKtj2NH9SIZOkHNmFAA:secret

Upload Using Access Keys and Bearer Token Auth

I. Create and sign the bearer token.

  1. Make the JSON object.

    Add the following content to the file token-bearer.json:

  2. Confirm that the file doesn’t end with a newline; if it does, truncate it to (size - 1). For example:
    truncate token-bearer.json --size 153

  3. Create a signature. For example:
    openssl dgst -sha512 -sign private_key.pem token-bearer.json | base64 > signature

  4. Create the signed token. For example:
    cat token-bearer.json  > token-bearer.json.signed
    echo "==SIGNATURE==" >> token-bearer.json.signed
    cat signature >> token-bearer.json.signed

  5. Construct the final token.
    cat token-bearer.json.signed | zlib-flate -compress  | base64 -w0 > token-bearer.json.sig.z.b64

  6. Test the token by browsing the top directory of the access key.
    curl -ki -H "X-Aspera-AccessKey: nEKTszy5gs9yFlZOnfc4dyzrnwKtj2NH9SIZOkHNmFAA" \
    -H "Authorization: Bearer eJwVkNmuolgARd/5DF/pKhlFTG7SCMikzIOeSqXCqCBwmKdK/3t7n/faKzv7L7Ib+7T7kye7064c3+m/Yd+kXfhz7Hf/ILs+hk36SWqYpD9rUXP7baWfPbteSmDUWUwl69bVszYUhC6zjgKMt6xXF447fVtPYVl+W9Klybu0/xMOHxWB4YcfOPGDwFwMP9H4iWLBN/Ts4Nh8dvS706/fyH/I15ejSDrnerb49YXwc7G0Fg4r8lIsJEfzHfM62tKkQWhL0WHNyMoebry5tqxoRXtBaettpiRt6vVyXwX+I342cXcVqLoIkGv5CASI8no+SoILb0LBzI8COrIkvArR3nIY9NA2FdQQRn1B8Yo1l5YmUxyA7pGgMhpr5sHF01UCNeKp74irWafha14TQvSI7dWb5CXBm4xNaYZOmSkynCQj49wluJS6ZPEwzjpZrRTyZeFuRzSTcFBztdgQNroCMFpGvArg0+RcM7DuTKBig2Yaoe9gCk9ukgS3yc555uaqiuOaU1zL/PWuev1lCPDM1mkjm449Mm6kSRJnT3lgYGWuWArwgBCBuiXuWagHqn9rDtO0bG8/k/loTEOEj1JR1cCZzSkApJveBPQ+b8klTZCXPXTeSzG1IYD5mV16zBzoTaLQAtBRqep4Lsr0Pr29vWE/R4EnkgIWQJVpVz/KuIPvE/7gjG1om/QTCVuxIXR+tAgg+mm5b3LQU0s2W+/btUInqNlbqNqa2WUFcfAEJ4wyp8M+h6RxW1oUd6krLy7imWrjCqltR+Uoj0ePh/JgnZc6L807YztmeM7J9nAzrps8C6wh2w9VkK6Eqa6mv6wvA70z/QbsJDmXFtBh14A7og80JqsPGkKOOr4moX9KyoG54JTSwf3EBxw2FvtjwDTP54NvcE14VcA3o3eQLQ2RF758jGJ2jamH+PxC/gc1nBpn" \

II. Give permissions to the bearer.

Permissions can be given to the top directory (file_id:1) or any subdirectory using their file_id. Permissions can be either edit or view and are recursive, meaning that top level permissions are inherited to subdirectories. The following is an example of setting a permission:

curl -ki -u nEKTszy5gs9yFlZOnfc4dyzrnwKtj2NH9SIZOkHNmFAA:secret \
https://localhost:9092/permissions -d '{"access_id":"", "access_type":"user", "access_level":"edit", "file_id":"1"}'

The following are examples of different types of uploads using a bearer token:

  • Export a bearer token for use in uploads:
    export ASPERA_SCP_TOKEN="Bearer eJwVkNmuolgARd/5DF/pKhlFTG7SCMikzIOeSqXCqCBwmKdK/3t7n/faKzv7L7Ib+7T7kye7064c3+m/Yd+kXfhz7Hf/ILs+hk36SWqYpD9rUXP7baWfPbteSmDUWUwl69bVszYUhC6zjgKMt6xXF447fVtPYVl+W9Klybu0/xMOHxWB4YcfOPGDwFwMP9H4iWLBN/Ts4Nh8dvS706/fyH/I15ejSDrnerb49YXwc7G0Fg4r8lIsJEfzHfM62tKkQWhL0WHNyMoebry5tqxoRXtBaettpiRt6vVyXwX+I342cXcVqLoIkGv5CASI8no+SoILb0LBzI8COrIkvArR3nIY9NA2FdQQRn1B8Yo1l5YmUxyA7pGgMhpr5sHF01UCNeKp74irWafha14TQvSI7dWb5CXBm4xNaYZOmSkynCQj49wluJS6ZPEwzjpZrRTyZeFuRzSTcFBztdgQNroCMFpGvArg0+RcM7DuTKBig2Yaoe9gCk9ukgS3yc555uaqiuOaU1zL/PWuev1lCPDM1mkjm449Mm6kSRJnT3lgYGWuWArwgBCBuiXuWagHqn9rDtO0bG8/k/loTEOEj1JR1cCZzSkApJveBPQ+b8klTZCXPXTeSzG1IYD5mV16zBzoTaLQAtBRqep4Lsr0Pr29vWE/R4EnkgIWQJVpVz/KuIPvE/7gjG1om/QTCVuxIXR+tAgg+mm5b3LQU0s2W+/btUInqNlbqNqa2WUFcfAEJ4wyp8M+h6RxW1oUd6krLy7imWrjCqltR+Uoj0ePh/JgnZc6L807YztmeM7J9nAzrps8C6wh2w9VkK6Eqa6mv6wvA70z/QbsJDmXFtBh14A7og80JqsPGkKOOr4moX9KyoG54JTSwf3EBxw2FvtjwDTP54NvcE14VcA3o3eQLQ2RF758jGJ2jamH+PxC/gc1nBpn"

  • Upload to directory with "file_id" : "1":
    ascp --tags='{"aspera":{"node":{"access_key":"nEKTszy5gs9yFlZOnfc4dyzrnwKtj2NH9SIZOkHNmFAA", "file_id":"1"}}}' \
    --mode=send --user=user_name -i /opt/aspera/var/aspera_tokenauth_id_rsa  -d  testfile01  /

  • Upload to subdirectory of "file_id" : "1":
    ascp --tags='{"aspera":{"node":{"access_key":"nEKTszy5gs9yFlZOnfc4dyzrnwKtj2NH9SIZOkHNmFAA", "file_id":"1"}}}' \
    --mode=send --user=user_name -i /opt/aspera/var/aspera_tokenauth_id_rsa  -d  testfile01  /tmp/DIR1/DIR2

  • Upload in a specific directory of "file_id" : "142":
    ascp --tags='{"aspera":{"node":{"access_key":"nEKTszy5gs9yFlZOnfc4dyzrnwKtj2NH9SIZOkHNmFAA", "file_id":"142"}}}' \
    --mode=send --user=user_name -i /opt/aspera/var/aspera_tokenauth_id_rsa  -d  testfile02  /tmp/DIR1/DIR2

Access Keys

This API can be accessed as with Basic auth using node user and password (with acl "key_master") or basic auth using access key and secret. For more information on the Storage Resource see the Storage Resource section in this document.

Access Key Resource


Create an Access Key

For creating access keys the 'id' can be used in sequential order to recover from backup if needed.

POST /access_keys
Authorization: Basic





Modify an Access Key

PUT /access_keys
Authorization: Basic



Delete an Access Key

DELETE /access_keys/{id}
Authorization: Basic

Get an Access Key

GET /access_keys/{id}
Authorization: Basic

Example Response


Storage Resource

Examples of each storage type and object is available below. Future extensions will include setting storage access restrictions and bandwidth restrictions for specific access keys.


Authorization Tokens

An authorization token authorizes a download or upload of one or more files into a directory (the destination root). Tokens can authorize transfers for both the traditional "cp" paradigm of Ascp (copy file1, file2, file3 to directory) as well as source/destination pairs (ascp --file-pair-list).

A transfer with a valid token behaves identically to transfers that don’t require tokens, as in the case where transfer authorization is set to allow on the Aspera server. When token authorization is required (when transfer authorization is set to token on the Aspera server), a transfer attempt made without a token or with an invalid token will fail with a Management authorization error specific to the problem encountered (missing token, invalid token, mismatched paths, and so on).

Generating and Using Tokens

The Node REST API provides an effective method for token generation. Transfer paths are defined in the transfer_requests JSON, along with source_root or destination_root, if needed.

Caution: Before generating and using tokens, review the guidelines in Token Validity Rules to help avoid serious errors with high-volume transfer implementations.

Transfer paths can be defined as any of the following. For brevity, the examples display paths only, not the entire transfer_requests JSON (for example, {"transfer_requests":[{"transfer_request":{"destination_root":"/foo","paths":[{"soure":"bar"}]}}]}). For full examples, please refer to the curl example for the /files/download_setup endpoint.

Download Sources


Upload Destinations


Source/Destination Pairs

The transfer_requests JSON is submitted to the Node API transfer setup resources to setup the transfer (/files/upload_setup for uploads and /files/download_setup for downloads).

The transfer_spec JSON returned by the Node API can then be used to start the transfer for the same paths defined in transfer_requests JSON.

Best Practices Steps Diagram

Token Gen Best Practices
Video player



Reset your Password Password resets are handled on the Support Site