Permissions

A Permission object represents a grant of access permission on a specific Path to a User or Group.

They can be optionally recursive or nonrecursive into the subfolders of that path.

A Permission may be applied to a User or a Group, but not both at once.

The following table sets forth the available Permission types:

PermissionAccess Level GrantedAutomatically Also Includes/Implies Permissions
adminAble to manage Folder Behaviors, Permissions, and Notifications for the folder. Also grants all other permissions.bundle, full, writeonly, readonly, list, history
bundleAble to share files and folders via a Bundle (share link).readonly, list
fullAble to read, write, move, delete, and rename files and folders. Also grants the ability to overwrite files upon upload.writeonly, readonly, list
historyAble to view the history of files and folders and to create email notifications for themselves.list
listAble to list files and folders, but not download.none
readonlyAble to list, preview, and download files and folders.list
readonly_site_adminAble to behave as a read-only Site Admin on a given child site. Only applies to child sites.readonly, list, history
site_adminAble to behave as a Site Admin on a given child site. Only applies to child sites.bundle, full, writeonly, readonly, list, history
writeonlyAble to upload files, create folders and list subfolders the user has write permission to.none

List Permissions

SDK Method

permission.List()

Return Object

[]*Permission

Authorization Requirement

Available to all authenticated keys or sessions.

PermissionListParams Fields

FieldDescription
Path
string		Permission path. If provided, will scope all permissions(including upward) to this path.
IncludeGroups
boolean		If searching by user or group, also include user's permissions that are inherited from its groups?
GroupId
string
PartnerId
string
UserId
string

Additional Arguments

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/permission"
)

permissionIterator, err := permission.List(files_sdk.PermissionListParams{Path: "example"})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for permissionIterator.Next() {
    permission := permissionIterator.permission()
}
err = permissionIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Create Permission

SDK Method

permission.Create()

Return Object

Permission

Authorization Requirement

Available to all authenticated keys or sessions.

PermissionCreateParams Fields

FieldDescription
Path
string
Required		Folder path
GroupId
int64		Group ID. Provide group_name or group_id
GroupIds
string		Group IDs when the permission requires multiple groups. If sent as a string, it should be comma-delimited.
Permission
string		Permission type. Can be admin, full, readonly, writeonly, list, or history
Recursive
boolean		Apply to subfolders recursively?
PartnerId
int64		Partner ID if this Permission belongs to a partner.
UserId
int64		User ID. Provide username or user_id
Username
string		User username. Provide username or user_id
GroupName
string		Group name. Provide group_name or group_id
SiteId
int64		Site ID. If not provided, will default to current site. Used when creating a permission for a child site.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/permission"
)

permission, err := permission.Create(files_sdk.PermissionCreateParams{Path: "path"})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Delete Permission

SDK Method

permission.Delete()

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

PermissionDeleteParams Fields

FieldDescription
Id
int64
Required		Permission ID.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/permission"
)

err := permission.Delete(files_sdk.PermissionDeleteParams{Id: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

The Permission Object

Some of the methods above return a Permission object. The attributes of this object are listed below.

AttributeDescription
Id
int64		Permission ID
Path
string		Path. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
UserId
int64		User ID
Username
string		Username (if applicable)
GroupId
int64		Group ID
GroupName
string		Group name (if applicable)
GroupIds
array(int64)		Group IDs when this permission requires multiple groups
GroupNames
array(string)		Group names when this permission requires multiple groups
PartnerId
int64		Partner ID (if applicable)
PartnerName
string		Partner name (if applicable)
Permission
string		Permission type. See the table referenced in the documentation for an explanation of each permission.
Possible values: full, readonly, writeonly, list, history, admin, bundle, site_admin, readonly_site_admin, previewonly
Recursive
boolean		Recursive: does this permission apply to subfolders?
SiteId
int64		Site ID