1. REST API for Documents
  2. Tasks
  3. Shares

Edit Shared Folder User Role

put

/documents/api/1.2/shares/{folderId}/role

Change the role of a user/group for a shared folder.

Request

Supported Media Types
Path Parameters

  • Globally unique identifier (GUID) for the folder. If the referenced folder is the user's home folder, the value for folderId is self

    .
Body ()
The request body defines details of the edit shared folder user role request. Bold indicates a required value.
Root Schema : ShareFolderEditRoleBody
Type: object
The request body defines details of the edit shared folder user role request. Bold indicates a required value.
Show Source
  • Optional message sent to the user.
  • Allowed Values: [ "viewer", "downloader", "contributor", "manager" ]

    Access level for the shared item:

    • viewer: Viewers can look at files and folders but can't change things.
    • downloader: Downloaders can also download files and save them to their own computers.
    • contributor: Contributors can also modify files, update files, upload new files, and delete files.
    • manager: Managers have all the privileges of the other roles and can add or remove other people as members.

  • Globally unique identifier (GUID) for the user, login name of the user, GUID for the group or a comma-separated list of the above (no more than 1000 total IDs).
Example Request (application/json)
{
    "userID":"U7ECC74059E0FEDFEC66BF5AT00000000001",
    "role":"viewer",
    "message":"Changing your shared access rights to viewer."
}
Back to Top

Response

Supported Media Types

200 Response

The request was fulfilled.

Body ()
Root Schema : ShareFolderResponse
Type: object
The response body includes share information along with user(s) or group(s) information.
Show Source
Nested Schema : members
Type: array
Users or groups with whom the folder is being shared in the current request.
Show Source
Nested Schema : User
Type: object
User information
Show Source
Nested Schema : items
Type: object
Show Source
  • User or group diplay name.
  • User or group identifier as supplied in the request body's userID parameter.
  • Whether adding this member was successful. (1) indicates success, (0) indicates failure.

  • Provisioning status for the user:

    • active: An active user that has been assigned an Oracle Content Management application role
    • inactive: A user that currently has no Content Management application roles assigned
    • deleted: A user that no longer exists in the IAM/IDCS identity domain.
    • pending: An external user that was invited but does not exist in the IAM/IDCS identity domain yet.

    Not returned if the type is group.

  • Member type, has value user or group.
Example Response (application/json)
{
    "errorCode":"0",
    "id":"F1321DC48E3B123D02DBEE88T0000000000100000001",
    "members":[
        {
            "id":"U7ECC74059E0FEDFEC66BF5AT00000000001",
            "displayName":"User BB",
            "type":"user",
            "isSuccessful":"1",
            "provisioningStatus":"active"
        }
    ],
    "role":"viewer",
    "type":"share",
    "user":{
        "id":"U7ECC74059E0FEDFEC66BF5AT00000000001",
        "displayName":"User BB",
        "type":"user"
    }
}

400 Response

Request parameters are not formatted correctly.

403 Response

Forbidden if the user does not have manager permission or there was a problem editing role for one or more user or group.

404 Response

Folder ID is not found.

Back to Top

Examples

The following example changes the access level to a given folder to 'viewer' for the specified user and group. 

PUT .../shares/F1321DC48E3B123D02DBEE88T0000000000100000001/role

Request Header

None.

Request Body

{
    "userID": "U7ECC74059E0FEDFEC66BF5AT00000000001,GS18003",
    "role": "viewer",
    "message": "Changing your shared access rights to viewer"
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
  "errorCode": "0",
  "id": "F1321DC48E3B123D02DBEE88T0000000000100000001",
  "members": [
    {
      "id": "U6A0B35B0548F250914D18FDB5D17B95F470",
      "displayName": "User BB",
      "type": "user",
      "isSuccessful": "1",
      "provisioningStatus": "active"
    },
    {
      "id": "GS18003",
      "displayName": "Sales Group",
      "type": "group",
      "isSuccessful": "1",
      "provisioningStatus": "active"
    }
  ],
  "role": "viewer",
  "type": "share",
  "user": {
    "id": "U6A0B35B0548F250914D18FDB5D17B95F470,GS18003",
    "type": "user"
  }
}

Example 2

The following example returns an error because the userID parameter is missing from the request body. 

PUT .../shares/F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F/role

Request Header

None.

Request Body

{
    "role": "viewer",
    "message": "granting you shared access"
}

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "errorCode": "-97",
    "errorKey": "!csUnableToEditSharingRole!csRequiredServiceParameterMissing,dUserID,EDIT_SHARING_ROLE",
    "errorMessage": "Failed to change shared user role. Parameter 'dUserID' required by service EDIT_SHARING_ROLE is missing.",
    "errorType": "share",
    "id": "F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F",
    "role": "viewer",
    "title": "Failed to change shared user role. Parameter 'dUserID' required by service EDIT_SHARING_ROLE is missing.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 3

The following example returns an error because the folder ID is invalid.

PUT .../shares/F2CCCC5706AEC8BD04260B2F45B3E9DD64907CA0D19F/role

Request Header

None.

Request Body

{
    "userID": "U5C4D5FCE14F2B44946FA74745B3E9DD6490",
    "role": "manager"
}

HTTP Status Code

HTTP_STATUS = 404

JSON Response

{
    "errorCode": "-16",
    "errorKey": "!csUnableToEditSharingRole!csSecurityValidationFailed!csFldDoesNotExist,F2CCCC5706AEC8BD04260B2F45B3E9DD64907CA0D19F!csUnprivilegedSystemError",
    "errorMessage": "Failed to change shared user role. Security validation failed. 'F2CCCC5706AEC8BD04260B2F45B3E9DD64907CA0D19F' does not exist. The error was caused by an internally generated issue. The error has been logged.",
    "errorType": "share",
    "id": "F2CCCC5706AEC8BD04260B2F45B3E9DD64907CA0D19F",
    "role": "manager",
    "title": "Failed to change shared user role. Security validation failed. 'F2CCCC5706AEC8BD04260B2F45B3E9DD64907CA0D19F' does not exist. The error was caused by an internally generated issue. The error has been logged.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "user": {
        "id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490",
        "type": "user"
    }
}
Back to Top