/access_keys

This API creates and manages access keys, which enable tenant-level access control over a given storage. Use access keys for authorization if the client application interacts with the Node API through a server application broker. For detailed information, see Authentication and Authorization.

Requirements
  • Available as of Enterprise Server version 3.6.0.
Access Control
  • HTTP Basic Auth
    Provide a node username and password (with acl "key_master") or an access key and secret. Access keys can be created for storage within the node user's restriction or within the authenticating access key's storage path.
Headers

All requests to this endpoint use the same 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

Endpoint Actions

Create a New Access Key

Create a new access key that grants authorization to the specified storage.

URL
POST https://{domain}:9092/access_keys

Sample Request
curl -i -u user:secret -X POST https://localhost:9092/access_keys \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d @request_body.json

Where request_body.json contains the following:
{
    "id" : "ak_1234",
    "secret" : "j3489tht42o8y32unifhkfw38ty238h3rih",
    "token_verification_key" : "9mgr3wtl4utmf394ur2ur52jgj934864ginsrh",
    "storage" : {},
    "license" : {
        "customer_id" : "customer1",
        "entitlement_id" : "43gsdi459-23r3r-w38ron-23523ro-sr82h3r8h3r"
    },
    "configuration" : {
        "transfer" : {
            "cipher" : "aes-128",
            "policy" : "fair",
            "target_rate_kbps" : 10000,
            "target_rate_cap_kbps" : 20000,
            "content_protection_secret" : "secretsecret",
            "preserve_timestamps" : false,
            "aggressiveness" : 0.00,
        },
        "server" : {
            "activity_event_logging" : true,
            "recursive_counts" : true
        }
    },
    "files_filelock_enabled" : true,
    "files_filelock_restriction" : "none"
}

Request Body
Element Required Type Description
id Optional String ID of the access key. Returns 209 (conflict) if it already exists. If it is not provided, the Node API creates an ID and returns the value in the response.
secret Required String Access key secret.
token_verification_key Optional String A token key that is configured on the node and used to authenticate token bearers.
storage Required JSON Storage specification object. See examples following this table.
license Optional JSON object Entitlement information, similar to regular Aspera On Demand. This is needed when the access key logs against Safenet.
customer_id Optional String Customer ID
entitlement_id Optional String ID of the entitlement
configuration Optional JSON object The transfer and server configuration object.
transfer Optional JSON object The transfer configuration object. Available as of 3.8.0.
cipher Optional String The minimum cipher allowed by the server for transfers that are authorized by this access key. Value can be none, aes-128, aes-192, or aes-256. Default is aes-128. To set the client-side cipher, set a value for cipher in the POST request body for /ops/transfers. Available as of 3.8.0.
policy Optional String The policy allowed for transfers that are authorized by this access key. Value can be high, regular, fair, low, trickle, or fixed. Aspera recommends against setting the policy to fixed, which can result in the transfer rate exceeding network or storage capacity if the client also requests a high minimum transfer rate that is not capped by the server. This can decrease transfer performance and cause problems on the target storage. To avoid these problems, set the allowed policy to fair. Available as of 3.8.0.
target_rate_kbps Optional Integer The default initial rate for transfers that are authorized by this access key, in kilobits per second. Available as of 3.8.0.
target_rate_cap_kbps Optional Integer The maximum target rate for transfers that are authorized by this access key, in kilobits per second. Available as of 3.8.0.
content_protection_secret Optional String Provide a password to require that content be encrypted by the client (enforce client-side encryption-at-rest) for transfers that are authorized by this access key. Available as of 3.8.0.
preserve_timestamps Optional Boolean Set to true to preserve file access and modification timestamps for transfers that are authorized by this access key. The server configuration overrides the access key configuration. Timestamp support in object storage varies by provider; consult your object storage documentation to determine which settings are supported. Default is false. Available as of 3.8.0.
aggressiveness Optional Float The aggressiveness of transfers that are authorized by this access key in claiming available bandwidth. Value can be 0.00-1.00. Available as of 3.8.0.
server Optional JSON object The server configuration object. Available as of 3.8.0.
activity_event_logging Optional Boolean Set to true to allow the Node API to query transfers that are associated with this access key through the /events endpoint. The access key configuration overrides the server configuration and must be enabled for event reporting to Aspera Files. Default is false. Available as of 3.8.0.
recursive_counts Optional Boolean Set to true to enable recursive counts. This option must be enabled for event reporting to Aspera Files. Default is false. Available as of 3.8.0.
files_filelock_enabled Optional Boolean Set to true to allow the access key user to create filelocks. Filelocks cannot be set if filelocks are disabled on the server (files_filelock_enabled is set to false in aspera.conf). Available as of 3.8.0.
files_filelock_restriction Optional String Set to none to allow the access key user to write, delete, or rename files if they are not locked or if the filelock was applied by the user. Set to write to allow the access key user to write, delete, or rename files only if the filelock was applied by the user. Available as of 3.8.0.
The Storage Object

The storage object specifies the type of storage and contains authorization credentials for non-local storage. The storage parameters depend on the type of storage.

Storage Type Syntax
Local
"storage" : {
    "type" : "local",
    "path" : "path"
}
Amazon S3
"storage" : {
    "type" : "aws_s3",
    "endpoint" : "s3.amazonaws.com",
    "bucket" : "bucket",
    "path" : "path",
    "storage_class" : "STANDARD|REDUCED_REDUNDANCY|INFREQUENT_ACCESS",
    "server_side_encryption" : "AES256|AWS_KMS",
    "server_side_encryption_aws_kms_key_id" = "arn_encryption_key",
    "credentials" : {
        "type" : "key|iam-role|assume-role",
        "access_key_id" : "aws_access_key",
        "secret_access_key" : "secret_access_key",
        "iam_role_name" : "iam_role",
        "assume_role_arn": "arn:aws:iam::your_aws_account_id:role/role_name",
        "assume_role_external_id" : "external_id",
        "assume_role_session_name" : "session_name"
    }
}
Where:
  • If server side encryption is set to "AWS_KMS", then "server_side_encryption_key_id" is required and is set to the ARN of the encryption key (for example, "arn:aws:kms:us-east-1:648543846928:key/er23525-8754-84g4-8sf7-4834ngigfre45").
  • Values for credentials depend on the type of authentication you use. To authenticate with your storage access key ID and secret, only specify "access_key_id" and "secret_access_key". To authenticate with an IAM role, only specify "iam_role_name". To authenticate with an assumed IAM role, only specify "assume_role_arn", "assume_role_external_id", and "assume_role_session_name".
Azure (Block and Page Storage)
"storage" : {
    "type" : "azure-block | azure-page",
    "container" : "container",
    "path" : "path",
    "storage_endpoint" : "blob.core.windows.net",
    "credentials" : {
        "type": "key",
        "account" : "account_name",
        "key" : "storage_access_key"
    }
}
Azure SAS
"storage" : {
    "type" : "azure_sas",
    "path" : "container/path",
    "api": "BLOCK|PAGE"
    "credentials" : {
        "shared_access_signature" : "shared_url"
    }
}
Where the "shared_access_signature" is the shared URL, such as https://company.blob.core.windows.net/temp?sv=2014-02-14&sr=c&sig=yfew...79uXE%3D&st=2015-07-29T07%3A00%3A00Z&se=2018-08-06T07%3A00%3A00Z&sp=rwdl.
Azure Files
"storage" : {
    "type" : "azure-files",
    "path" : "share/path",
    "credentials" : {
        "file_service_endpoint" : "https://account.file.core.windows.net/",
        "password" : "password"
    }
}
Google Cloud Storage Authenticated by a service account with a private key:
"storage": {
    "type" : "google-gcs",
    "storage_endpoint" : "storage.googleapis.com",
    "path" : "bucket/path",
    "max_segments_per_compose" : 10000,
    "credentials": {
      "type": "service_account",
      "project_id": "project_id", 
      "private_key_id": "key_id",
      "private_key": "-----BEGIN PRIVATE KEY-----key_string-----END PRIVATE KEY-----\n",
      "client_email": "client_id@developer.gserviceaccount.com",
    }
}
Authenticated by an OAuth token:
"storage" : {
    "type" : "google-gcs",
    "storage_endpoint" : "storage.googleapis.com",
    "path" : "bucket/path",
    "max_segments_per_compose" : 1024,
    "credentials" : {
      "type" : "oauth",
      "client_id" : "client_id",
      "client_secret" : "secret"
      "project_id" : "project_id",
      "access_token" : "access_token",
      "refresh_token" : "refresh_token",
      "token_expiration" : "token_lifetime_seconds"
      "auth_uri" : "https://accounts.google.com/o/oauth2/auth", 
      "token_uri" : "https://accounts.google.com/o/oauth2/token",
      "auth_provider_x509_cert_url" : "https://www.googleapis.com/oauth2/v1/certs",
      "client_x509_cert_url" : "https://www.googleapis.com/robot/v1/metadata/x509/client_id%40developer.gserviceaccount.com"
    }
}
IBM Cloud Object Storage (COS) - S3
"storage" : {
  "type" : "ibm-s3",
  "bucket" : "bucket",
  "path" : "path",
  "endpoint" : "s3-api.us-geo.objectstorage.service.networklayer.com",
  "credentials" : {
	"type" : "key",
	"access_key_id" : "key_id",
	"secret_access_key" : "key_secret"
  }
}
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

{
    "id": "local_access_key",
    "root_file_id": "1",
    "token_verification_key" : null,
    "license" : null,
    "storage" : {
        "type" : "local",
        "path" : "/projectA"
    },
    "configuration" : {
        "transfer" : {
            "cipher" : "aes-128",
            "policy" : "fair",
            "target_rate_kbps" : 10000,
            "target_rate_cap_kbps" : 20000,
            "content_protection_secret" : "secretsecret",
            "preserve_timestamps" : false,
            "aggressiveness" : "0.00",
        },
        "server" : {
            "activity_event_logging" : true,
            "recursive_counts" : true
        }
    },
    "files_filelock_enabled" : true,
    "files_filelock_restriction" : "none"
}

Status Codes and Errors
Code Description Notes
200 OK Success
400 Bad Request Error Request contains a formatting or syntax error.
500 Internal Server Error Error Invalid server configuration
Response
The response body returns the same information as the request body, including the storage object but not including the secret. If a storage path is specified, the root file ID is also returned.

Get Information about All Access Keys

Get information about all the access keys to which the authentication method has access.

URL
GET https://{domain}:9092/access_keys

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/access_keys \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

[
{
  "id" : "ak_group1",
  "root_file_id" : "1",
  "token_verification_key" : null,
  "license" : null,
  "storage" : {
    "type" : "local",
    "path" : "/projects/projectA"
  }
},
{
  "id" : "ak_user2",
  "root_file_id" : "1",
  "token_verification_key" : null,
  "license" : null,
  "storage" : {
    "type" : "local",
    "path" : "/projects/projectB"
  }
}
]

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 Request contains an invalid access key ID
500 Internal Server Error Error Invalid server configuration
Response
The response body returns the same information as creating an access key, including the storage object but not including the secret, for all access keys. If a storage path is specified, the root file ID is also returned.

Get Information about a Specific Access Key

Get information about an access key to which the authentication method has access, specified by access key ID.

URL
GET https://{domain}:9092/access_keys/{id}

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/access_keys/{id} \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Query Parameters
To return storage or license information for versions 3.6.0 through 3.7.4, use the following query parameters. These can be combined to return both, in which case the URL is https://{domain}:9092/access_keys/{id}?embed%5b%5d=storage&embed%5b%5d=license. As of 3.8.0, license and storage information is automatically included in the response.
Parameter Type Description Values
embed[] string Include storage and license information in the response. storage to return storage information, license to return license information.
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

{
"id" : "ak_group1",
"root_file_id" : "1",
"token_verification_key" : null,
"license" : null,
"storage" : {
    "type" : "local",
    "path" : "/projects/projectA"
}
}

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 Request contains an invalid access key ID
500 Internal Server Error Error Invalid server configuration
Response
Same as for creating an access key, including the storage object but not including the secret, for the specified access key. If a storage path is specified, the root file ID is also returned.

Get Information about the Access Key that is Associated with your Token

If you are authenticating with a basic token or bearer token, you can get information about the access key that is associated with your token. This returns the same information as a GET request to /access_keys/{id}, but you do not need to know the access key ID.

URL
GET https://{domain}:9092/access_keys/self

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/access_keys/self \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Query Parameters
To return storage or license information for versions 3.6.0 through 3.7.4, use the following query parameters. These can be combined to return both, in which case the URL is https://{domain}:9092/access_keys/{id}?embed%5b%5d=storage&embed%5b%5d=license. As of 3.8.0, license and storage information is automatically included in the response.
Parameter Type Description Values
embed[] string Include storage and license information in the response. storage to return storage information, license to return license information.
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

{
"id" : "ak_group1",
"root_file_id" : "1",
"token_verification_key" : null,
"license" : null,
"storage" : {
    "type" : "local",
    "path" : "/projects/projectA"
}
}

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 Request contains an invalid access key ID
500 Internal Server Error Error Invalid server configuration
Response
Same as for creating an access key, including the storage object but not including the secret, for the specified access key. If a storage path is specified, the root file ID is also returned.

Modify an Access Key

Update an access key configuration with the specified values.

URL
PUT https://{domain}:9092/access_keys/{id}

Sample Request
curl -i -u user:secret -X PUT https://{domain}:9092/access_keys/{id} \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"target_rate_kbps":0}'

Request Body
Same as for creating an access key. The request body can contain all or only the updated element-value pairs.
Sample Response
Same as for creating an access key.
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 Request contains an invalid access key ID
500 Internal Server Error Error Invalid server configuration
503 Service Unavailable Error The access key is locked for modification because it is being deleted.

Delete an Access Key

Delete a specific access key.

URL
DELETE https://{domain}:9092/access_keys/{id}

Sample Request
curl -i -u user:secret -X DELETE https://{domain}:9092/access_keys/{id}

Sample Responses

Success:

HTTP/1.1 204 No Content
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
Content-Length: 0

Error:

{
      "error":{
         "code":404,
         "reason":"Not Found",
         "user_message':"Access key (id='testkey') does not exist.")
      }
}

Error:

{
      "error":{
         "code":403,
         "reason":"Forbidden",
         "user_message':"Can't delete an access_key using the same access_key.")
      }
}

Status Codes and Errors
Code Description Notes
204 No Content Success Access key deleted.
400 Bad Request Error Request contains a formatting or syntax error.
404 Not Found Error Request contains an invalid access key ID
500 Internal Server Error Error Invalid server configuration
503 Service Unavailable Error Access key is locked because it is in use or being backed up.
Video player

Video

×