Permission Manager (REST)

The Relativity REST API supports operations on permissions though the Permission Manager service. The operations available through the service are equivalent to the asynchronous methods for interacting with the permissions in the Relativity Services API. For more information, see Permissions.

Note: You can only use the POST method when interacting with the service.

Client code sample

The following is an example of .NET REST code for returning groups with admin permissions. You can use this code for all Permission Manager service operations with different endpoint URLs and input JSON values.

Copy 
//Set up the REST client.
            
HttpClient httpClient = new HttpClient();
httpClient.BaseAddress = new Uri("http://localhost/");

//Set the required headers.
            
httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
httpClient.DefaultRequestHeaders.Add("Authorization", "Basic c2FtcGxlYWRtaW5AcmVsYXRpdml0eS5yZXN0OlMwbTNwQHNzdzByZA==");

//Call get groups with admin permissions.
            
string url = "/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetAdminGroupSelectorAsync";
StringContent content = new StringContent(CreateInputJSON, Encoding.UTF8, "application/json");
HttpResponseMessage response = httpClient.PostAsync(url, content).Result;
string result = response.Content.ReadAsStringAsync().Result;
bool success = HttpStatusCode.Created == response.StatusCode;

//Parse the result with Json.NET.
            
JObject resultObject = JObject.Parse(result);

Get admin groups

Use this Permission Manager service URL to return groups with admin permissions enabled and disabled:

Copy 
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetAdminGroupSelectorAsync

The request does not include any input parameters.

The response returns a GroupSelector object. Group Selector includes the EnabledGroups and DisabledGroups properties that list groups with and without admin permissions.

Get workspace groups

Use this Permission Manager service URL to return groups with workspace permissions enabled and disabled:

Copy 
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetWorkspaceGroupSelectorAsync

The request must include the workspace Artifact ID:

Copy 
{
  "workspaceArtifactID": 13758822
}

The response includes the EnabledGroups and DisabledGroups properties that list groups with and without workspace permissions.

Get item groups

Use this Permission Manager service URL to return groups with item permissions enabled and disabled:

Copy 
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetItemGroupSelectorAsync

The request must include the Artifact IDs for the workspace and the item:

Copy 
{
  "workspaceArtifactID": 13758822,
  "artifactID": 17234345
}

The response returns includes the EnabledGroups and DisabledGroups properties that list groups with and without item permissions.

Add and remove admin groups

Use this Permission Manager service URL to add and remove groups to and from admin permissions:

Copy 
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/AddRemoveAdminGroupsAsync

The request must include a valid JSON representation of the GroupSelector object. It is recommended that you first return a GroupSelector, and then manipulate it by moving the groups into the EnabledGroups and DisabledGroups collections as GroupRef objects. For simplicity you can set the enabled and disabled groups to only the groups you wish to modify. All other groups will not be altered within the GroupSelector object when setting the values.

Note: The GroupSelector object must have the latest value of LastModified, and every call that returns GroupSelector will update this value. This prevents a user from reading a value and modifying it if another user has read that value with the intent of changing it as well. Item-level security must be enabled to add or remove groups to the permissions for individual items.

Copy 
{
  "groupSelector": {
    "DisabledGroups": [
      {
        "ArtifactID": 1015027,
      }
    ],
    "EnabledGroups": [
      {
        "ArtifactID": 1015005,
      },
      {
        "ArtifactID": 1015028,
      },
      {
        "ArtifactID": 1015029,
      },
      {
        "ArtifactID": 1015030,
      }
    ],
    "LastModified": "2015-02-23T17:03:23.413"
  }
}

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes.

Add and remove workspace groups

Use this Permission Manager service URL to add and remove groups to and from workspace permissions:

Copy 
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/AddRemoveWorkspaceGroupsAsync

The request must include a workspace Artifact ID and a valid JSON representation of the GroupSelector object. It is recommended that you first return a GroupSelector, and then manipulate it by moving the groups into the EnabledGroups and DisabledGroups collections as GroupRef objects. For simplicity you can set the enabled and disabled groups to only the groups you wish to modify. All other groups will not be altered within the GroupSelector object when setting the values.

Note: The GroupSelector object must have the latest value of LastModified, and every call that returns GroupSelector will update this value. This prevents a user from reading a value and modifying it if another user has read that value with the intent of changing it as well. Item-level security must be enabled to add or remove groups to the permissions for individual items.

Copy 
{ 
  "workspaceArtifactID": 1343243,
  "groupSelector": {
    "DisabledGroups": [
      {
        "ArtifactID": 1015027
      }
    ],
    "EnabledGroups": [
      {
        "ArtifactID": 1015005
      },
      {
        "ArtifactID": 1015028
      },
      {
        "ArtifactID": 1015029
      },
      {
        "ArtifactID": 1015030
      }
    ],
    "LastModified": "2015-02-23T17:03:23.413"
  }
}

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes.

Add and remove item groups

Use this Permission Manager service URL to add and remove groups to and from item permissions:

Copy 
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/AddRemoveItemGroupsAsync;

The request must include the workspace and item Artifact IDs and a valid JSON representation of the GroupSelector object. It is recommended that you first return a GroupSelector, and then manipulate it by moving the groups into the EnabledGroups and DisabledGroups collections as GroupRef objects. For simplicity you can set the enabled and disabled groups to only the groups you wish to modify. All other groups will not be altered within the GroupSelector object when setting the values.

Note: The GroupSelector object must have the latest value of LastModified, and every call that returns GroupSelector will update this value. This prevents a user from reading a value and modifying it if another user has read that value with the intent of changing it as well. Item-level security must be enabled to add or remove groups to the permissions for individual items.

Copy 
{
    "workspaceArtifactID": 1343243,
    "artifactID": 1673243,
    "groupSelector": {
    "DisabledGroups": [
      {
        "ArtifactID": 1015027,
      }
    ],
    "EnabledGroups": [
      {
        "ArtifactID": 1015005,
      },
      {
        "ArtifactID": 1015028,
      },
      {
        "ArtifactID": 1015029,
      },
      {
        "ArtifactID": 1015030,
      }
    ],
    "LastModified": "2015-02-23T17:03:23.413"
  }
}

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes.

Get admin permissions

Use this Permission Manager service URL to return the admin permissions for a group:

Copy 
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetAdminGroupPermissionsAsync

The request must include a valid JSON representation of the GroupRef object.

Copy 
{
  "group": {
    "ArtifactID": 13761061
  }
}

The response contains the group's admin permissions.

Get workspace permissions

Use this Permission Manager service URL to return the workspace permissions for a group:

Copy 
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetWorkspaceGroupPermissionsAsync

The request must include a workspace Artifact ID and a valid JSON representation of the GroupRef object.

Copy 
{
  "workspaceArtifactID": 13758822,
  "group": {
    "ArtifactID": 13761061
  }
}

The response contains the group's permissions to the workspaces.

Get item permissions

Use this Permission Manager service URL to return the item permissions for a group:

Copy 
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetItemGroupPermissionsAsync

The request must include Artifact IDs of the workspace and the item and a valid JSON representation of the GroupRef object.

Copy 
{
  "workspaceArtifactID": 13758822,
  "ArtifactID": 1038413,
  "group": {
    "ArtifactID": 1036399  
  }
}

The response contains the group's permissions to the item. Note that the set of permissions can be different depending on the item's object type. The following is an example of Document permissions.

Set admin permissions

Use this Permission Manager service URL to set the admin permissions for a group:

Copy 
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/SetAdminGroupPermissionsAsync

The request must include a valid JSON representation of the GroupPermissions object containing the admin permissions set. It is recommended that you first return GroupPermissions object and then inspect and manipulate the permissions within it.

The response does not contain any data. Success or failure are indicated by the HTTP status code. For more information, see HTTP status codes.

Set workspace permissions

Use this Permission Manager service URL to set a group's workspace permissions:

Copy 
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/SetWorkspaceGroupPermissionsAsync

The request must include a workspace Artifact ID and a GroupPermissions object containing the workspace permissions set. It is recommended that you first return the GroupPermissions object and then inspect and manipulate the permissions within it.

The response does not contain any data. Success or failure are indicated by the HTTP status code. For more information, see HTTP status codes.

Get item-level security

Use these Permission Manager service endpoints to check if item-level security is enabled:

 

GetItemLevelSecurityAsync

Use this Permission Manager service URL to check if item-level security is enabled for a single artifact:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetItemLevelSecurityAsync

The request must include Artifact IDs of the workspace and the item:

Copy
{
  "workspaceArtifactID": 13758822,
  "ArtifactID": 1038413
}

The response indicates whether item-level security is enabled:

Copy
{
  "ArtifactID": 1038593,
  "Enabled": false,
  "LastModified": "2015-02-24T02:17:14.07"
}

GetItemLevelSecurityListAsync

Use this Permission Manager service URL to check if item-level security is enabled for multiple artifacts:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetItemLevelSecurityListAsync

The request must include Artifact IDs of the workspace and a list of ArtifactIDs of the items:

Copy
{
  "workspaceArtifactID": -1,
  "artifactIDs": [13757815, 13766087, 13766089]
}

The response indicates whether item-level security is enabled for each artifact:

Copy
{
  "13757815": {
    "ArtifactID": 13757815,
    "Enabled": true,
    "LastModified": "2015-08-11T20:17:57.463"
  },
  "13766087": {
    "ArtifactID": 13766087,
    "Enabled": false,
    "LastModified": "2015-08-11T20:17:57.463"
  },
  "13766089": {
    "ArtifactID": 13766089,
    "Enabled": true,
    "LastModified": "2015-08-11T20:17:57.463"
  }
}

Set item-level security

Use this Permission Manager service URL to enable or disable item-level security:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/SetItemLevelSecurityAsync

The request must include Artifact IDs of the workspace and the item, and a valid itemLevelSecurity object:

Copy
{
  "workspaceArtifactID": 13758841,
  "itemLevelSecurity": {
    "ArtifactID": 1038593,
    "Enabled": true,
    "LastModified": "2015-02-24T02:17:14.07"
  }
}

Note that the value of the LastModified property must match the existing value on the itemLevelSecurity object. You can retrieve it using the GetItemLevelSecurityAsync or GetItemLevelSecurityListAsync endpoints described above.

The response does not contain any data. Success or failure are indicated by the HTTP status code. For more information, see HTTP status codes.

Set item permissions

If security is enabled, use this Permission Manager service URL to set item permission:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/SetItemGroupPermissionsAsync

The request must include a workspace Artifact ID and a GroupPermissions object containing the item permissions set. It is recommended that you first return GroupPermissions object and then inspect and manipulate the permissions within it. Note that the permissions can be different depending on the object type of the item. The following is an example of Document permissions.

Copy
{
  "workspaceArtifactID": 1234567,
  "artifactID": 2334435,
  "groupPermissions": {
    "ArtifactID": 1038413,
    "GroupID": 1036399,
    "ObjectPermissions": [
      {
        "ArtifactGroupingID": 9,
        "Name": "Document",
        "ViewSelected": true,
        "EditEditable": true,
        "EditSelected": true,
        "DeleteEditable": true,
        "DeleteSelected": false,
        "AddEditable": false,
        "AddSelected": false,
        "EditSecurityEditable": true,
        "EditSecuritySelected": false,
        "CanRemovePermissions": false,
        "SubPermissions": [
          {
            "PermissionID": 1000002,
            "Name": "Print / Save As PDF",
            "Selected": false
          },
          {
            "PermissionID": 1000005,
            "Name": "Local Access (Download, Copy Text)",
            "Selected": false
          },
          {
            "PermissionID": 1000006,
            "Name": "Redact Document",
            "Selected": true
          },
          {
            "PermissionID": 1000007,
            "Name": "Highlight Document",
            "Selected": true
          },
          {
            "PermissionID": 1000018,
            "Name": "Add Image",
            "Selected": true
          },
          {
            "PermissionID": 1000019,
            "Name": "Delete Image",
            "Selected": false
          }
        ],
        "CustomPermissions": [],
        "HasChildPermissions": false,
        "HierarchyIndent": 2,
        "ArtifactTypeID": 10,
        "ParentArtifactTypeID": 9
      }
    ],
    "TabVisibility": [],
    "BrowserPermissions": [],
    "MassActionPermissions": [],
    "AdminPermissions": [],
    "LastModified": "2015-02-22T00:34:43.813"
  }
}

The response does not contain any data. Success or failure are indicated by the HTTP status code. For more information, see HTTP status codes.

Get admin group users

Use this Permission Manager service URL to return a list of users in a group with admin permissions:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetAdminGroupUsersAsync

The request must specify the group:

Copy
{
  "group": {
    "ArtifactID": 1015029
  }
}

The response contains the list of users in the group:

Copy
[
  {
    "ArtifactID": 13758829,
    "Name": "Doe, Jane"
  },
  {
    "ArtifactID": 13758839,
    "Name": "Doe, John"
  },
  {
    "ArtifactID": 13758845,
    "Name": "Sample, JC"
  }
]

Get workspace group users

Use this Permission Manager service URL to return a list of users in a group with workspace permissions:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetWorkspaceGroupUsersAsync

The request must specify the workspace Artifact ID and the group:

Copy
{
  "workspaceArtifactId": 13758822,
  "group": {
    "ArtifactID": 1015029
  }
}

The response contains the list of users in the group:

Copy
[
  {
    "ArtifactID": 13758829,
    "Name": "Doe, Jane"
  },
  {
    "ArtifactID": 13758839,
    "Name": "Doe, John"
  },
  {
    "ArtifactID": 13758845,
    "Name": "Sample, JC"
  }
]

Get item group users

Use this Permission Manager service URL to return a list of users in a group with item permissions:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetItemGroupUsersAsync

The request must specify the Artifact IDs, the item, and the group:

Copy
{
  "workspaceArtifactId": 13758822,
  "artifactID": 1038524,
  "group": {
    "ArtifactID": 1015029
  }
}

The response contains the list of users in the group:

Copy
[
  {
    "ArtifactID": 13758829,
    "Name": "Doe, Jane"
  },
  {
    "ArtifactID": 13758839,
    "Name": "Doe, John"
  },
  {
    "ArtifactID": 13758845,
    "Name": "Sample, JC"
  }
]

Query permissions

Use this Permission Manager service URL to query permissions:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/QueryAsync

The request must specify the workspace Artifact ID, the query, and optionally the number of results to return as the length property. To query admin permissions, specify -1 as workspace Artifact ID. The following is an example of a query request for view permissions with the result set sorted by ArtifactID in descending order.

Copy
{
  "workspaceArtifactID": 13758822,
  "query": {
    "Condition": "'PermissionType' == 'View'",
    "Sorts": [
      {
        "FieldIdentifier": {
          "Name": "PermissionID"
        },
        "Order": 0,
        "Direction": 1
      }
    ]
  },
  "length":5
}

If more results are available than initially specified in the length property, the query returns a token value that is not null. The results can subsequently be retrieved by a call to the QuerySubsetAsync operation.

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/QuerySubsetAsync

Note that the QuerySubsetAsync request can specify the starting index of the result subset and the number of results to be returned.

Copy
{
  "queryToken": "a5079c32-e080-473d-846e-941ef6a5f086",
  "start": 6,
  "length": 5
}

To return all permissions in a workspace or all admin permissions, omit the Condition property in the Query object. When the length parameter is not specified, its value defaults to 0, and the number of returned results defaults to the Configuration Table value of PDVDefaultQueryCacheSize of 10000. For more information, see Searching Relativity.

The response is a collection of permissions.

Copy
{
  "QueryToken": "614b4e40-8c67-47cb-b09d-57b150b8167e",
  "TotalCount": 5,
  "Success": true,
  "Message": "",
  "Results": [
    {
      "Success": true,
      "Artifact": {
        "Name": "Add ProductionDataSource",
        "ArtifactType": {
          "ID": 1000034,
          "Guids": [
            "7528c416-3706-4909-8805-edddcf75542d"
          ]
        },
        "PermissionID": 1000240,
        "PermissionType": {
          "ID": 6,
          "Name": "Add"
        }
      },
      "Message": "",
      "WarningMessages": []
    },
    {
      "Success": true,
      "Artifact": {
        "Name": "Secure ProductionDataSource",
        "ArtifactType": {
          "ID": 1000034,
          "Guids": [
            "7528c416-3706-4909-8805-edddcf75542d"
          ]
        },
        "PermissionID": 1000239,
        "PermissionType": {
          "ID": 4,
          "Name": "Secure"
        }
      },
      "Message": "",
      "WarningMessages": []
    },
    {
      "Success": true,
      "Artifact": {
        "Name": "Delete ProductionDataSource",
        "ArtifactType": {
          "ID": 1000034,
          "Guids": [
            "7528c416-3706-4909-8805-edddcf75542d"
          ]
        },
        "PermissionID": 1000238,
        "PermissionType": {
          "ID": 3,
          "Name": "Delete"
        }
      },
      "Message": "",
      "WarningMessages": []
    },
    {
      "Success": true,
      "Artifact": {
        "Name": "Edit ProductionDataSource",
        "ArtifactType": {
          "ID": 1000034,
          "Guids": [
            "7528c416-3706-4909-8805-edddcf75542d"
          ]
        },
        "PermissionID": 1000237,
        "PermissionType": {
          "ID": 2,
          "Name": "Edit"
        }
      },
      "Message": "",
      "WarningMessages": []
    },
    {
      "Success": true,
      "Artifact": {
        "Name": "View ProductionDataSource",
        "ArtifactType": {
          "ID": 1000034,
          "Guids": [
            "7528c416-3706-4909-8805-edddcf75542d"
          ]
        },
        "PermissionID": 1000236,
        "PermissionType": {
          "ID": 1,
          "Name": "View"
        }
      },
      "Message": "",
      "WarningMessages": []
    }
  ]
}

Read a single permission

If you already know the permission ID, for example, by performing a query, you can quickly read the permission without constructing a query.

Use this Permission Manager service URL to get selected permissions for the current user:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetPermissionSelectedAsync

The request must specify the workspace Artifact ID and the permission ID.

Copy
{
  "workspaceArtifactID": 13758822,
  "permissionID": 1000238
}

The response represents a single permissions object.

Copy
{
  "Name": "Delete ProductionDataSource",
  "ArtifactType": {
    "ID": 1000034,
    "Guids": [
      "7528c416-3706-4909-8805-edddcf75542d"
    ]
  },
  "PermissionID": 1000238,
  "PermissionType": {
    "ID": 3,
    "Name": "Delete"
  }
}

Get selected permissions for current user

Permission Manager service provides the following endpoints for returning the specified permissions for the current user:

  • GetPermissionSelectedAsync - returns a collection of permission values for the current user. You can also specify an ArtifactID to return permissions of an item with security enabled.
  • GetPermissionSelectedListAsync - is similar to GetPermissionSelectedAsync, but instead of only returning permissions for one artifact, you can pass in a list of ArtifactIDs to return a dictionary that maps the ArtifactID to the permissions.

GetPermissionSelectedAsync

Use this Permission Manager service URL to get selected permissions for the current user:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetPermissionSelectedAsync

The request must specify the workspace Artifact ID and a collection of permissions objects. The following is an example of a payload to check if the current user has the View, Add, Delete, and Update permissions for documents. Note that the permissions are identified by the combination of the artifact type ID (10) and permission type ID (1, 2, 3, and 6).

Copy
{
  "workspaceArtifactID": 13772405,
  "permissions": [
   {
    "ArtifactType": {
      "ID": 10
    },
    
    "PermissionType": {
      "ID": 1
    }
  },
  {
    "ArtifactType": {
      "ID": 10
    },
    
    "PermissionType": {
      "ID": 2
    }
  },
  {
    "ArtifactType": {
      "ID": 10
    },
    
    "PermissionType": {
      "ID": 3
    }
  },
  {
    "ArtifactType": {
      "ID": 10
    },
    
    "PermissionType": {
      "ID": 6
    }
  },
  ]
}

To return permissions for an object with item-level security enabled, you must also pass in the Artifact ID of the object. The following is the payload for returning the edit permissions for an agent security enabled. Note that because an agent is an admin-level object, -1 is specified as workspace ArtifactID.

Copy
{
  "workspaceArtifactID": -1,
  "permissions": [
    {
      "ArtifactType": {
        "ID": 20
      },
      "PermissionType": {
        "ID": 2
      }
    }
  ],
  "ArtifactID": 13757815
}

The "Selected" attribute of the objects returned by the response indicates whether the specified permissions are enabled for the current user.

Copy
[
  {
    "Selected": true,
    "Name": "View Document",
    "ArtifactType": {
      "ID": 10,
      "Guids": [
        "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
      ]
    },
    "PermissionID": 44,
    "PermissionType": {
      "ID": 1,
      "Name": "View"
    }
  },
  {
    "Selected": true,
    "Name": "Edit Document",
    "ArtifactType": {
      "ID": 10,
      "Guids": [
        "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
      ]
    },
    "PermissionID": 45,
    "PermissionType": {
      "ID": 2,
      "Name": "Edit"
    }
  },
  {
    "Selected": true,
    "Name": "Delete Document",
    "ArtifactType": {
      "ID": 10,
      "Guids": [
        "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
      ]
    },
    "PermissionID": 46,
    "PermissionType": {
      "ID": 3,
      "Name": "Delete"
    }
  },
  {
    "Selected": true,
    "Name": "Add Document",
    "ArtifactType": {
      "ID": 10,
      "Guids": [
        "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
      ]
    },
    "PermissionID": 43,
    "PermissionType": {
      "ID": 6,
      "Name": "Add"
    }
  }
]

GetPermissionSelectedListAsync

Use this Permission Manager service URL to get the current user's permissions to specified artifacts:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetPermissionSelectedListAsync

The request must specify the workspace Artifact ID, a collection of permissions objects, and a collection of ArtifactIDs of Relativity objects. The following is an example of a payload to check if the current user has the View, Add, Delete, and Update permissions for agents. Note that because an agent is an admin-level object, -1 is specified as workspace ArtifactID and the permissions are identified by the combination of the artifact type ID (20) and permission type ID (1, 2, 3, and 6).

Copy
{
  "workspaceArtifactID": -1,
  "permissions": [
    {
      "ArtifactType": {
        "ID": 20
      },
      "PermissionType": {
        "ID": 1
      }
    },

    {
      "ArtifactType": {
        "ID": 20
      },
      "PermissionType": {
        "ID": 2
      }
    },
    {
      "ArtifactType": {
        "ID": 20
      },
      "PermissionType": {
        "ID": 3
      }
    },
    {
      "ArtifactType": {
        "ID": 20
      },
      "PermissionType": {
        "ID": 6
      }
    }
  ],
  "artifactIDs": [13757815, 13757821,13766087]
}

The response is a dictionary of permissions values for each ArtifactID. The "Selected" attribute indicates whether the specified permissions are enabled for the current user.

Copy
{
  "13757815": [
    {
      "Selected": true,
      "Name": "View Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 147,
      "PermissionType": {
        "ID": 1,
        "Name": "View"
      }
    },
    {
      "Selected": true,
      "Name": "Edit Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 148,
      "PermissionType": {
        "ID": 2,
        "Name": "Edit"
      }
    },
    {
      "Selected": true,
      "Name": "Delete Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 149,
      "PermissionType": {
        "ID": 3,
        "Name": "Delete"
      }
    },
    {
      "Selected": true,
      "Name": "Add Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 151,
      "PermissionType": {
        "ID": 6,
        "Name": "Add"
      }
    }
  ],
  "13757821": [
    {
      "Selected": true,
      "Name": "View Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 147,
      "PermissionType": {
        "ID": 1,
        "Name": "View"
      }
    },
    {
      "Selected": true,
      "Name": "Edit Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 148,
      "PermissionType": {
        "ID": 2,
        "Name": "Edit"
      }
    },
    {
      "Selected": true,
      "Name": "Delete Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 149,
      "PermissionType": {
        "ID": 3,
        "Name": "Delete"
      }
    },
    {
      "Selected": true,
      "Name": "Add Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 151,
      "PermissionType": {
        "ID": 6,
        "Name": "Add"
      }
    }
  ],
  "13766087": [
    {
      "Selected": true,
      "Name": "View Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 147,
      "PermissionType": {
        "ID": 1,
        "Name": "View"
      }
    },
    {
      "Selected": true,
      "Name": "Edit Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 148,
      "PermissionType": {
        "ID": 2,
        "Name": "Edit"
      }
    },
    {
      "Selected": true,
      "Name": "Delete Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 149,
      "PermissionType": {
        "ID": 3,
        "Name": "Delete"
      }
    },
    {
      "Selected": true,
      "Name": "Add Agent",
      "ArtifactType": {
        "ID": 20,
        "Guids": []
      },
      "PermissionID": 151,
      "PermissionType": {
        "ID": 6,
        "Name": "Add"
      }
    }
  ]
}

Get selected permissions for a group

Use this Permission Manager service URL to get selected permissions for a specified group:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/GetPermissionSelectedforGroupAsync

The request must specify the workspace Artifact ID, a collection of permissions objects, and the group. The following is an example of a payload to check if the group has the Add permissions for documents.

Copy
{
  
  "workspaceArtifactID": 13772405,
  "permissions": [
  {
    "ArtifactType": {
      "ID": 10
    },
    
    "PermissionType": {
      "ID": 6
    }
  }
  ],
  "group": {"ArtifactID": 1015028}

}

To return permissions for an object with item-level security enabled, you must also pass in the Artifact ID of the object. The following is the payload for returning a groups edit permissions for an agent with security enabled.

Copy
{
  "workspaceArtifactID": -1,
  "permissions": [
    {
      "ArtifactType": {
        "ID": 20
      },
      "PermissionType": {
        "ID": 2
      }
    }
  ],
  "group": {
    "ArtifactID": 1015028
  },
  "ArtifactID": 13757815
}

The "Selected" attribute of the objects returned by the response indicates whether the specified permissions are enabled for the group.

Copy
[
  {
    "Selected": false,
    "Name": "Edit Agent",
    "ArtifactType": {
      "ID": 20,
      "Guids": []
    },
    "PermissionID": 148,
    "PermissionType": {
      "ID": 2,
      "Name": "Edit"
    }
  }
]

Set selected permissions for a group

Use this Permission Manager service URL to set selected permissions for a group:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/SetPermissionSelectedforGroupAsync

The request must specify the workspace Artifact ID, a collection of permissionValues objects, and the group. The permissionsValues objects must identify the permission and specify whether the permission is enabled (selected). The following is an example of a payload to disable the edit and delete document permissions for a group.

Copy
{
  "workspaceArtifactID": 13772405,
  "permissionValues": [
    
    {
      "PermissionID": 45,
      "Selected": false
    },
        {
      "PermissionID": 46,
      "Selected": false
    }
  ],
  "group": {
    "ArtifactID": 13772407
  }
}

To set selected permissions for an object with item-level security enabled, you must also pass in the Artifact ID of the object. The following is the payload for setting a group's edit permissions for an agent with security enabled. Note that the group must be already associated with the item.

Copy
{
  "workspaceArtifactID": -1,
  "permissionValues": [
    {
      "PermissionID": 148,
      "Selected": true
    }
  ],
  "group": {
    "ArtifactID": 1015028
  },
  "ArtifactID": 13757815
}

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes.

Create a custom permission

Use this Permission Manager service URL to create a custom permission for a Relativity Dynamic Object (RDO):

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/CreateSingleAsync

The request must include a valid JSON representation of a permission. The ArtifactType ID must match the ArtifactType ID of the RDO, and the PermissionType of "Custom" must be specified.

Copy
{
  "workspaceArtifactID": 13772535,
  "permissionDTO": {
    "Name": "Additional Comments",
    "ArtifactType": {
      "ID": 1000035
    },
    "PermissionType": {
      "ID": 11,
      "Name": "Custom"
    }
  }
}

The response is the ID of the created custom permission.

Update a custom permission

Use this Permission Manager service URL to update a custom permission for an RDO:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/CreateSingleAsync

The request must identify the permission by Permission ID and include an updated permission name.

Copy
{
  "workspaceArtifactID": 13772535,
  "permissionDTO": {
    "Name": "Reviewer Notes",
    "PermissionID": 1000251
  }
}

The response does not contain any data. Success or failure are indicated by the HTTP status code. For more information, see HTTP status codes.

Delete a custom permission

Use this Permission Manager service URL to delete a custom permission:

Copy
<host>/Relativity.REST/api/Relativity.Services.Permission.IPermissionModule/Permission%20Manager/CreateSingleAsync

The request must identify include the workspace Artifact ID and the permission the permission ID.

Copy
{
  "workspaceArtifactID": 13772535,
  "permissionID": 1000251
}

The response does not contain any data. Success or failure are indicated by the HTTP status code. For more information, see HTTP status codes.