Update segment or folder permissions

Learn more about replacing the access control list for a segment or folder.

The Update segment or folder permissions replaces the role-based access control list (ACL) for a segment or folder. Only the owner of the segment or folder, or a tenant admin, can call this API. Sending an empty object removes all role-based restrictions and reverts the segment or folder to its default owner- and sharing-based access.

HTTP method and endpoint

Use the following HTTP method and endpoint path to update the permissions for a segment or folder.

PUT {envUri}/reltio/api/{tenantId}/segments/{id}/_permissions

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`tenantId`	String	Yes	Unique identifier of the tenant.
`id`	String	Yes	Unique identifier of the segment or folder.

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	Bearer `<access_token>`	Yes
`Content-Type`	application/json	Yes

Request body

The following table describes the request body parameters.


Parameter	Type	Required	Description	Accepted values / Default
(root object)	Object	Yes	A map of role name to access level. Each key is a non-blank role name; each value is the access level granted to that role. A role name cannot repeat in the request body. The request body can contain up to 100 roles. An empty object (`{}`) clears the ACL. A `null` body is rejected.	`READ`, `WRITE`.

Example request

Use the following example to update the permissions for a segment or folder.

PUT {envUri}/reltio/api/{tenantId}/segments/{id}/_permissions
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "ROLE_SALES": "READ",
  "ROLE_MKT": "WRITE"
}

The following example shows how to clear all role-based restrictions for a segment or folder.

PUT {envUri}/reltio/api/{tenantId}/segments/{id}/_permissions
Authorization: Bearer <access_token>
Content-Type: application/json

{}

Response body

On success, the response returns 200 OK with the updated access control list.


Field	Type	Description
(root object)	Object	A map of role name to access level, reflecting the ACL that was just set. Each key is a role name; each value is `READ` or `WRITE`. If the request clears the ACL, the API returns `{}`.

Example response

The following example shows a 200 OK response after setting roles on a segment or folder.

{
  "ROLE_SALES": "READ",
  "ROLE_MKT": "WRITE"
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Error code	Description	Recommended action
`400 Bad Request`	`INVALID_SEGMENT_PERMISSIONS`	The request body is `null`, contains a blank role name, a `null` or null access level, or exceeds 100 entries.	Correct the ACL payload and then resend the request.
`400 Bad Request`	`FAILED_TO_PARSE_JSON_CONTENT`	The request body contains a duplicate role name, or an access level that is not `READ` or `WRITE`.	Remove duplicate role entries and use only `READ` or `WRITE` as the access level.
`403 Forbidden`	`SEGMENT_FORBIDDEN`	The caller is neither the owner of the segment or folder nor a tenant admin, or lacks READ access to a folder that contains the segment or folder.	Request that the segment or folder owner, or a tenant admin, make this change, or grant you the required access.
`404 Not Found`	`SEGMENT_NOT_FOUND`	The segment or folder with the specified ID does not exist.	Verify the segment or folder ID, and then retry the request.

Unify and manage your data