REST API Reference > Platform REST API version 3 resources > Object permissions
  

Object permissions

Use the objects resource to configure user and user group permissions to objects such as assets, folders, and projects.
To configure permissions for an object, create an access control list (ACL) for each user or user group that might interact with the object. Each ACL specifies a user or user group and their access rights for the object.
For example, you want the NorthDevTeam and WestDevTeam user groups to have read/write access to the NorthwestAccounts project. You create an ACL to specify the NorthDevTeam's access rights to the NorthwestAccounts project, and then create an ACL to specify the WestDevTeam's access rights to the NorthwestAccounts project.
You can use the objects resource to perform the following tasks to manage permissions:

Creating permissions

Create an access control list (ACL) for each user or user group and object pair.

POST request

To create an ACL, send a POST request using the following URI:
/public/core/v3/objects/<object ID/permissions
Include the following information:
Field
Type
Required
Description
principal
Object
Yes
Whether the ACL is defined for a user or user group and the name of the user or user group.
type
String
Yes
Include in principal object.
Use one of the following values:
  • - USER
  • - GROUP
name
String
Yes
Include in principal object.
Name of the object.
permissions
Object
Yes
Object permissions to assign to the user or group.
read
Boolean
Yes
Include in permissions object.
Whether to allow the user or group to view the object.
delete
Boolean
Yes
Include in permissions object.
Whether to allow the user or group to delete the object.
execute
Boolean
Yes
Include in permissions object.
Whether to allow the user to run the task.
changePermission
Boolean
Yes
Include in permissions object.
Whether to allow the user or group to change the permissions for the object.

POST response

If successful, returns the object with the details you included in the POST request plus the ACL ID.

POST example

To create user permissions for an object, you might send a request similar to the following example:
POST <baseApiUrl>/public/core/v3/objects/9EcgvBYZ9GGflOYr98GzOH/permissions
Content-Type: application/json
Accept: application/json
INFA-SESSION-ID: <sessionId>
{
"principal": {
"type":"USER",
"name":"larry@infa.com"
},
"permissions" : {
"read" : true,
"update" : true,
"delete" : true,
"execute" : true,
"changePermission" : true
}
}
You might receive a response similar to the following example:
[
{
"id": "0dXigiEiWRbb5rKLgPfFCe",
"principal": {
"type": "USER",
"name": "larry@infa.com"
},
"permissions": {
"read": true,
"update": true,
"delete": true,
"execute": true,
"changePermission": true
}
}
]

Updating permissions

You can update an access control list (ACL) to change the access rights that a user or user group has for an object.

PUT request

To update an ACL, send a PUT request using the following URI:
/public/core/v3/objects/<object ID>/permissions/<ACL ID>
Include the following information:
Field
Type
Required
Description
principal
Object
Yes
Whether the permission is defined for a user or user group and the name of the user or user group.
type
String
Yes
Include in principal object.
Use one of the following values:
  • - USER
  • - GROUP
name
String
Yes
Include in principal object.
Name of the object.
permissions
Object
Yes
Object permissions to assign to the user or group.
read
Boolean
Yes
Include in permissions object.
Whether to allow the user or group to view the object.
delete
Boolean
Yes
Include in permissions object.
Whether to allow the user or group to delete the object.
execute
Boolean
Yes
Include in permissions object.
Whether to allow the user to run the task.
changePermission
Boolean
Yes
Include in permissions object.
Whether to allow the user or group to change the permissions for the object.

PUT response

Returns a success code if successful or an error object if errors occur.

PUT example

To update user permissions for an object, you might send a request similar to the following example:
PUT <baseApiUrl>/public/core/v3/objects/9EcgvBYZ9GGflOYr98GzOH/permissions/4eMlUawPcahhK4eKBmDLsI
Content-Type: application/json
Accept: application/json
INFA-SESSION-ID: <sessionId>
{
"principal": {
"type":"USER",
"name":"scotty@infa.com"
},
"permissions" : {
"read" : true,
"update" : true,
"delete" : true,
"execute" : false,
"changePermission" : true
}
}

Deleting permissions

You can delete the permissions that a user or user group has for an object or delete all of the permissions configured for an object.
To delete the permissions that a user or user group has for an object, send a DELETE request using the following URI:
/public/core/v3/objects/<object ID>/permissions/<ACL ID>
To delete all of the permissions configured for an object, send a DELETE request using the following URI:
/public/core/v3/objects/<object ID>/permissions
For example, to delete all of the permissions for an object, you might send a request similar to the following request:
DELETE <baseApiUrl>/public/core/v3/objects/9EcgvBYZ9GGflOYr98GzOH/permissions

Getting permission details

You can get permission details for particular ACL ID or get the details for all permissions on an object.

GET request

To get the details for a particular ACL ID, send a GET request using the following URI:
/public/core/v3/objects/<object ID>/permissions/<ACL ID>
To get the details for all permissions on an object, send a GET request using the following URI:
/public/core/v3/objects/<object ID>/permissions

GET response

If successful, returns the following information for an ACL ID:
Field
Type
Description
id
String
ACL ID
principal
Object
Information about the user or group.
type
String
Whether the principal is a user or group.
name
String
User name or name of the user group.
permissions
Object
Object permissions for the user or group.
read
Boolean
Whether the user or group can view the object.
update
Boolean
Whether the user or group can update the object.
delete
Boolean
Whether the user or group can delete the object.
execute
Boolean
Whether the user or group can run the task.
changePermission
Boolean
Whether the user or group can change the permissions for the object.

Get example

To get the details for all permissions on a object, you might send a request that's similiar to the following example:
/public/core/v3/objects/2ymkhUZCl7XbUmN7dsq6Wc/permissions
You might receive a response similar to the following example:

[
{
"id": "4D6ER3yic8cjjE1GmxEKEi",
"principal": {
"type": "USER",
"name": "saki@infa.com"
},
"permissions": {
"read": true,
"update": true,
"delete": true,
"execute": true,
"changePermission": true
}
},
{
"id": "6g51tCtEX08bldfh8k6cgz",
"principal": {
"type": "GROUP",
"name": "Everyone"
},
"permissions": {
"read": false,
"update": true,
"delete": true,
"execute": false,
"changePermission": true
}
}
]

Checking permissions

You can send a request to check your access rights for a particular object or asset type. The response is based on the permissions and privileges for the user who started the current session.
You might want to check your access rights before you attempt to create an asset in a project or folder. If you don't have permissions for the project or folder, the value of "false" will show for each permission type.

GET request

To get your access rights for an object, send a GET request using the following URI:
/public/core/v3/objects/<object ID>/permissions/checkAccess
The response includes your access rights for the given object ID.
To find out if you can create a particular type of asset in a project or folder, send a GET request that includes the project or folder ID and the asset type. Use the following URI:
/public/core/v3/objects/<object ID>/permissions/checkAccess?type=<asset type>
For a list of asset types, see Finding an asset.

GET examples

To check your access rights for an object, you might send a request similar to the following example:
GET <baseApiUrl>/public/core/v3/objects/2ymkhUZCl7XbUmN7dsq6Wc/permissions/checkAccess
You might receive a response similar to the following example:
{
"permissions": {
"create": true,
"read": true,
"update": true,
"delete": true,
"execute": false,
"changePermission": true
}
}
To see if you have permissions to create a Data Integration mapping in a project, you might send a request similar to the following example:
GET <baseApiUrl>/public/core/v3/objects/2ymkhUZCl7XbUmN7dsq6Wc/permissions/checkAccess?type=DTEMPLATE
You might receive a response similar to the following example:
{
"permissions": {
"create": true,
"read": true,
"update": true,
"delete": true,
"execute": true,
"changePermission": true
}
}