/permissions

This API creates and manages file permissions and access levels for Node API users who authenticate with bearer tokens. Access key users, access key owners, and other admin users have all access levels permissions.

Each permission includes a user or group ID and access levels (file actions such as list, read, and delete). Permission access levels apply recursively and cumulatively; once a user has a certain access level to a directory, they have at least that level of access to all children. An access level permission allows the user to give or remove the same permission to others.

Requirements
  • Available as of Enterprise Server version 3.6.0.
Access Control
  • HTTP Basic Auth
    Provide an access key ID and secret.
  • Bearer token
    Actions are restricted to the tenant space defined by the bearer token and the access levels set on the content for the user or group IDs that are specified in the bearer token.
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
X-Aspera-AccessKey Required
(for bearer token authorization)
The access key ID that was used to create the bearer token. Access key ID.
Authorization Required
(for bearer token authorization)
The bearer token. Bearer token_string
Status Codes and Errors
Code Description Notes
200 OK Success
400 Bad Request Error Request contains a formatting or syntax error.
403 Forbidden Error The user does not have accesss to create a permission.
404 Not Found Error Invalid permission ID.
409 Conflict Error The permission already exists.
500 Internal Server Error Error The server configuration is invalid.

Endpoint Actions

Create a Permission

Apply permissions to a file or directory for a specific user.

Restrictions
  • Accessible only if the user has any permision (recursively) on the associated file.
URL
POST https://{domain}:9092/permissions

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

Where request_body.json contains the following:
{
    "file_id" : "file_id",
    "access_type" : "type",
    "access_id" : "user_id",
    "access_levels" : [
        "permission1", 
        "permission2"…
        ],
    "tags" : {
        "tag1" : "tag_string"
        }
}

Request Body
Element Required Type Description
file_id Required String The ID of the file to which to apply the permissions.
access_type Required String The access type, either user or group.
access_id Required String The user ID, if access_type is or group ID.
access_levels Required (versions after 3.7.4) String A list of access levels for the user or group. Available as of version 3.7.4. Values can be:
  • list - view the files in a path
  • read - read file content (including preview) and upload file
  • write - create files (but not directories) and download files
  • delete - delete the file
  • mkdir - create directory
  • rename - rename the file
  • preview - read file preview
With any permission, the user can access file metadata.
access_level Required (versions before 3.7.4) String The access level for the user. Deprecated as of version 3.7.4. Values can be view or edit. view is equivalent to list + read + preview. edit is equivalent to having all access levels.
tags Optional JSON User-defined tags. Tags can be used as search terms for GET requests.
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: clse
Content-Type: application/json; charset=utf-8

{
  "id" : "1",
  "file_id" : "50",
  "access_id" : "aspera",
  "access_type" : "user",
  "access_levels" : [
    "list",
    "read",
    "write",
    "delete"
  ],
  "tags" : null,
  "created_by_id" : "ASPERA_ACCESS_KEY_ADMIN",
  "created_at" : "2018-02-13T17:54:38Z",
  "last_updated_by_id" : "ASPERA_ACCESS_KEY_ADMIN",
  "last_updated_at" : "2018-02-13T17:54:38Z"
}

Response
Element Type Description
id String Unique ID of the permission.
file_id String The ID of the file.
access_id String The user ID or group ID.
access_type String The access type, either user or group.
access_levels String The access levels granted by the permission for the user or group. Returned by version 3.7.4 or later.
access_level String The access level granted by the permission for the user or group. Returned by versions older than 3.7.4.
tags JSON User-defined tags.
created_by_id String The ID of the permission creator.
created_at String Time when the permission was created, in ISO format.
last_updated_by_id String The ID of the user who last updated the permission.
last_updated_at String Time when the permission was modified, in ISO format.

Get Permissions Information

Get information about permissions and optionally filter the response.

Restrictions
  • The response includes only permissions that apply to the user, unless the user has any permissions on the root file, in which case all permission are returned.
URL
GET https://{domain}:9092/permissions

Sample Request
curl -i -u user:secret \
    -X GET https://{domain}:9092/permissions?page=1&per_page=5&access_levels%5B%5D=write&embed%5B%5D=file \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

Query Parameters
Parameter Type Description Values
file_id String Get all permissions, including inherited (recursive) permissions, for the file. Requires any permission (recursively) on the file. file_id
inherited Boolean Use with file_id to retrieve all permissions with or without inherited (recursive) permissions. Requires any permission (recursively) on the file. true, false
access_type String Use with access_id to retrieve all permissions for the given access ID. Returns permission information only if the user is the access ID or has any permissions to the root file. Otherwise, filters permissions by access ID. user, group
access_id String Use with access_type to retrieve all permissions for the given access ID. Returns permission information only if the user is the access ID or has any permissions to the root file. Otherwise, filters permissions by access ID. access_id
created_by_id String Retrieve all permissions for the given ID. Returns permission information only if the user is the created by ID or has any permissions to the root file. Otherwise, filters permissions by created by ID and excludes inherited permissions. created_by_id
page Unsigned integer Return the permissions as pages. Use with per_page to set the number of permissions returned per page. The page number to return.
per_page Unsigned integer Return the specified number of permissions per page. Number
embed[] String Embed the file metadata in the response. file
access_levels[] String Filter permissions by access levels. Available as of version 3.7.4. Filter by multiple access levels by using multiple queries. list, read, write, delete, mkdir, rename, preview
access_level String Filter permissions by access level. For versions older than 3.7.4. edit or view
last_updated_by_id String Filter permissions by last_updated_by_id and exclude inherited permissions. last_updated_by_id
tags String Filter permissions by tag and exclude inherited permissions. tag_id(tag_value)
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: clse
Content-Type: application/json; charset=utf-8
Access-Control-Expose-Headers: X-Total-Count
X-Total-Count: 1

{
  "id" : "1",
  "file_id" : "50",
  "file" : {
    "id" : "50",
    "name" : "sample.txt",
    "path" : "/Users/aspera/Documents/sample.txt",
    "size" : 424,
    "type" : "file",
    "modified_time" : null,
    "content_type" : "text/plain"
  },
  "access_id" : "aspera",
  "access_type" : "user",
  "access_levels" : [
    "list",
    "read",
    "write",
    "delete"
  ],
  "tags" : null,
  "created_by_id" : "ASPERA_ACCESS_KEY_ADMIN",
  "created_at" : "2018-02-13T17:54:38Z",
  "last_updated_by_id" : "ASPERA_ACCESS_KEY_ADMIN",
  "last_updated_at" : "2018-02-13T17:54:38Z"
}

Response
Element Type Description
id String Unique ID of the permission.
file_id String The ID of the file.
file JSON A JSON array containing the file metadata. Returned only for requests that include embed[]=file.
id String The file ID (same as file_id). Returned only for requests that include embed[]=file.
name String The file name. Returned only for requests that include embed[]=file.
path String The full filepath. Returned only for requests that include embed[]=file.
size String The size of the file, symbolic link, or directory, in bytes. Returned only for requests that include embed[]=file.
type String The file type (file, symbolic link, or folder). Returned only for requests that include embed[]=file.
modified_time String The file creation time in ISO format. Returned only for requests that include embed[]=file.
content_type String The file format, such as application/octet-stream and text/plain. Returned only for requests that include embed[]=file.
access_id String The user ID or group ID.
access_type String The access type, either user or group.
access_levels String The access levels granted by the permission for the user or group. Returned by version 3.7.4 or later.
access_level String The access level granted by the permission for the user or group. Returned by versions older than 3.7.4.
tags JSON User-defined tags.
created_by_id String The ID of the permission creator.
created_at String Time when the permission was created, in ISO format.
last_updated_by_id String The ID of the user who last updated the permission.
last_updated_at String Time when the permission was modified, in ISO format.

Get Permissions Information for a Specific Permission

Get information about a specific permission by permission ID.

Restrictions
  • Accessible only if the user created the permission, is the target of the permission, or has any permision (recursively) on the associated file.
URL
GET https://{domain}:9092/permissions/{id}

Sample Request
curl -i -u user:secret \
    -X GET https://{domain}:9092/permissions/{id}?embed%5B%5D=file \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

Query Parameters
Parameter Type Description Values
embed[] String Embed the file metadata in the response. file
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: clse
Content-Type: application/json; charset=utf-8

{
  "id" : "1",
  "file_id" : "50",
  "file" : {
    "id" : "50",
    "name" : "sample.txt",
    "path" : "/Users/aspera/Documents/sample.txt",
    "size" : 424,
    "type" : "file",
    "modified_time" : null,
    "content_type" : "text/plain"
  },
  "access_id" : "aspera",
  "access_type" : "user",
  "access_levels" : [
    "list",
    "read",
    "write",
    "delete"
  ],
  "tags" : null,
  "created_by_id" : "ASPERA_ACCESS_KEY_ADMIN",
  "created_at" : "2018-02-13T17:54:38Z",
  "last_updated_by_id" : "ASPERA_ACCESS_KEY_ADMIN",
  "last_updated_at" : "2018-02-13T17:54:38Z"
}

Response
Element Type Description
id String Unique ID of the permission.
file_id String The ID of the file.
file JSON A JSON array containing the file metadata. Returned only for requests that include embed[]=file.
id String The file ID (same as file_id). Returned only for requests that include embed[]=file.
name String The file name. Returned only for requests that include embed[]=file.
path String The full filepath. Returned only for requests that include embed[]=file.
size String The size of the file, symbolic link, or directory, in bytes. Returned only for requests that include embed[]=file.
type String The file type (file, symbolic link, or folder). Returned only for requests that include embed[]=file.
modified_time String The file creation time in ISO format. Returned only for requests that include embed[]=file.
content_type String The file format, such as application/octet-stream and text/plain. Returned only for requests that include embed[]=file.
access_id String The user ID or group ID.
access_type String The access type, either user or group.
access_levels String The access levels granted by the permission for the user or group. Returned by version 3.7.4 or later.
access_level String The access level granted by the permission for the user or group. Returned by versions older than 3.7.4.
tags JSON User-defined tags.
created_by_id String The ID of the permission creator.
created_at String Time when the permission was created, in ISO format.
last_updated_by_id String The ID of the user who last updated the permission.
last_updated_at String Time when the permission was modified, in ISO format.

Modify a Permission

Modify the access levels or tags associated with a permission.

Restrictions
  • A user can only modify permissions on a file if they were the creator or have any permissions (recursively) on the file.
  • Only the access levels or tags can be modified. To change other settings, delete the permission and recreate it with the new values.
URL
PUT https://{domain}:9092/permissions/{id}

Sample Request
curl -i -u user:secret -X PUT https://{domain}:9092/permissions/{id} \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"access_levels":"["write","read","mkdir"]}'

Request Body
Element Required Type Description
access_levels Optional String The updated array of access levels for version 3.7.4 or later. Values: list, read, write, delete, mkdir, rename, or preview. Note: The updated list must include all the desired access levels, it is not an additive action.
access_level Optional String The updated access level for versions older than 3.7.4. Values: view or edit.
tags Optional String User-defined tag-value pairs.
Sample Response
The response is the same as for creating a permission and returns the updated permission information.

Delete a Permission

Delete a permission, specified by permission ID.

Restrictions
  • Accessible only if the user created the permission, or is the access key owner, or has an admin-level bearer token.
URL
DELETE https://{domain}:9092/permissions/{id}

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

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

Error:
HTTP/1.1 409 Conflict
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
Content-Length: 103

{
    "error" : { 
        "code" : 409, 
        "reason" : "Conflict", 
        "user_message" : "Permission already exists" 
    }
}

Response
Element Type Description
error JSON object Error response.
code Double HTTP error code.
reason String HTTP error message.
user_message String Error description.
Video player

Video

×