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

Share Folder

post

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

Share a specified folder with specified user(s) and/or group(s). When you share folders, you control the permissions each person/group has for the folder and its files by assigning a role to the person/group. The different roles determine what a person/group can do with a shared folder.
  • Viewer: Viewers can look at the contents of a folders but can't change files.
  • Downloader: Downloaders can also download files and save them to their own computer.
  • Contributor: Contributors can also modify, update, upload, and delete files. Contributors can also get metadata values, get metadata definitions, and set values for metadata already assigned by the folder owner.
  • Manager: Managers have all the privileges of the other roles and can add or remove other people as members.

Request

Supported Media Types
Path Parameters

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

    .
Body ()
The request body defines details of the share request. Bold indicates a required value.
Root Schema : ShareFolderBody
Type: object
The request body defines details of the share folder 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, folders, and assets but can't change things.
    • downloader: Downloaders can also download files and assets and save them to their own computers.
    • contributor: Contributors can also modify, update, upload, and delete files or assets.
    • 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":"manager",
    "message":"Granting you shared access to this folder."
}
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":"manager",
    "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 read permission or there was a problem with one or more supplied users or groups.

404 Response

Folder ID is not found.

Back to Top

Examples

The following example grants manager-level access to the specified folder.

POST .../shares/F1321DC48E3B123D02DBEE88T0000000000100000001

Request Header

None.

Request Body

{
    "userID": "U7ECC74059E0FEDFEC66BF5AT00000000001",
    "role": "manager",
    "message": "granting you shared access to this folder"
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
  "errorCode": "0",
  "id": "F1321DC48E3B123D02DBEE88T0000000000100000001",
  "members": [
    {
      "id": "U7ECC74059E0FEDFEC66BF5AT00000000001",
      "displayName": "User CC",
      "type": "user",
      "isSuccessful": "1",
      "provisioningStatus": "active"
    }
  ],
  "role": "manager",
  "type": "share",
  "user": {
    "displayName": "User CC",
    "loginName": "userCCLoginName",
    "id": "U7ECC74059E0FEDFEC66BF5AT00000000001",
    "type": "user"
  }
}

Example 2

The following example attempts to share a folder with the viewer role, but an error is returned because the user already has higher access to the folder. 

PUT .../shares/F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F

Request Header

None.

Request Body

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

HTTP Status Code

HTTP_STATUS = 403

JSON Response

{
    "errorCode": "-1",
    "errorKey": "!csUserAlreadyHasAccessToFolder,User DD,f2",
    "errorMessage": "User 'UserAA' already has access to folder 'f2' with identical or higher privileges.",
    "errorType": "share",
    "id": "F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F",
    "members":[
        {
            "id":"U5C4D5FCE14F2B44946FA74745B3E9DD6490",
            "displayName":"User DD",
            "type":"user",
            "isSuccessful":"0"
        }
    ],
    "role": "viewer",
    "title": "User 'User DD' already has access to folder 'f2' with identical or higher privileges.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "user": {
	"displayName": "User DD",
	"id": "U5C4D5FCE14F2B44946FA74745B3E9DD6490",
	"loginName": "userDDLoginName",
	"type": "user"
    }
}

Example 3

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

PUT .../shares/F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F

Request Header

None.

Request Body

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

HTTP Status Code

HTTP_STATUS = 400

JSON Response

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

Example 4

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

PUT .../shares/F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F

Request Header

None.

Request Body

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

HTTP Status Code

HTTP_STATUS = 404

JSON Response

{
    "errorCode": "-16",
    "errorKey": "!csUnableToShareFolder!csSecurityValidationFailed!csFldDoesNotExist,F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F!csUnprivilegedSystemError",
    "errorMessage": "Failed to share folder. Security validation failed. 'F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F' does not exist. The error was caused by an internally generated issue. The error has been logged.",
    "errorType": "share",
    "id": "F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F",
    "role": "manager",
    "title": "Failed to share folder. Security validation failed. 'F2CD745706AEC8BD04260B2F45B3E9DD64907CA0D19F' 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"
    }
}

Example 5

The following example shares a folder with two users (using user GUID and login name) and a group.

Request Header

None.

Request Body

{
    "userID": "U92A91A29A46767692583BCCCC4A88C356D9,JohnSmith,GS18003",
    "role": "manager",
    "message": "granting you shared access"
}

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
  "errorCode": "0",
  "id": "F6ED064539F10B076BC0F8E19AD1D511040A6D384E90",
  "members": [
    {
      "id": "U92A91A29A46767692583BCCCC4A88C356D9",
      "displayName": "David Lee",
      "type": "user",
      "isSuccessful": "1",
      "provisioningStatus": "active"
    },
    {
      "id": "JohnSmith",
      "displayName": "John Smith",
      "type": "user",
      "isSuccessful": "1",
      "provisioningStatus": "pending"
    },
    {
      "id": "GS18003",
      "displayName": "Sales Group",
      "type": "group",
      "isSuccessful": "1",
      "provisioningStatus": "active"
    }
  ],
  "role": "manager",
  "type": "share",
  "user": {
    "id": "U92A91A29A46767692583BCCCC4A88C356D9,JohnSmith,GS18003",
    "type": "user"
  }
}
Back to Top