Version: v5.0

Permissions

Create or Update Permissions#

This API call allows you to create or update permissions for platform resources in the Item Service, such as a NamedUserItem. The resources are specified using IRNs.

Note: Introduced in Platform version 4.5, there is now fine-grained support for updating permissions for RelatedItems. See Create or Update Permissions for RelatedItems below.

Endpoints#

PUT /itemsvc/api/v1/permissions

Parameters#

Body#

Parameter	Type	Description	Required
`_resourceDesc._irn`	String	The resource IRN, which consists of the following: `<service>:<resource type>:<resource ID>`, such as `itemsvc:nameduseritem:5cd3cd1c2ab79c0001572476`. You can also pass a pattern, such as `itemsvc:nameduseritem:*`. For more information on IRN patterns, see Look up permissions by IRN pattern.	Required
`_resourceDesc._criteria`	Object	Pass an object with a key-value pair for `_itemClass` or `_userType`.	Optional
`_namespace`	String	The namespace to which the resource belongs.	Required
`_user._type`	String	The permission user type, such as `"user"`, `"usergroup"`, or `"permprofile"`.	Required
`_user._id`	String	The permission user ID.	Required
`_actions`	Array of String	The actions that the user is authorized to perform on the resource, such as `"READ"`, `"CREATE"`, `"EDIT"`, `"DELETE"`, `"SHARE"` or `"*"` to permit all actions.	Required

Body example#

[  {    "_actions": [      "READ"    ],    "_namespace": "r_TmBKvZTI",    "_resourceDesc": {      "_irn": "itemsvc:nameduseritem:5cd3cd1c2ab79c0001572476"    },    "_user": {      "_type": "user",      "_id": "1f159053-657b-40f4-9897-434f9e2df8be"    }  }]

Response#

Response codes#

Code	Description
`200`	Success
`400`	Bad Request

Response#

{  "_success": [    {      "_actions": [        "READ"      ],      "_namespace": "r_TmBKvZTI",      "_resourceDesc": {        "_irn": "itemsvc:nameduseritem:5cd3cd1c2ab79c0001572476"      },      "_user": {        "_type": "user",        "_id": "ab38424d-69b2-4353-812e-78faac6ebd7a"      },      "_id": "1f159053-657b-40f4-9897-434f9e2df8be",      "_status": 200    }  ],  "_failures": []}

Create or Update Permissions for RelatedItems#

This API call allows you to configure permissions for specific RelatedItems which match a set of given criteria. It facilitates fine-grained access control of RelatedItems which match the criteria query.

When using this API call, note the following:

This API call uses the same permission end point as listed above for the existing Create or Update Permisssions API call, but also uses _subresourceDesc.
_resourceDesc._subresourceDesc._criteria must be a valid RelatedItem query.
The permission is applicable only for the RelatedItem(s) matching the criteria query.
Users are restricted to accessing only the RelatedItems that match the specified criteria. This applies to all APIs, including GET /relateditems/:id, GET /relateditems, PUT /relateditems, PUT /relateditems/:id, DELETE /relateditems/:id, and /search (covering all operators).
It provides READ access to NamedUserItem, But it doesn't provide any additional access to NamedUserItem.
_subresourceDesc can be specified only when the IRN refers to specific NamedUserItem. For example: itemsvc:nameduseritem:6333e105026300398e2d653e. It cannot be used for IRN(s) such as itemsvc:nameduseritem:*
Users should be able to retrieve RelatedItems they have access to within a NamedUserCollection. If a user holds multiple permissions, all applicable permissions will be evaluated using an OR condition when retrieving RelatedItems.
Permissions tied to _subresourceDesc apply strictly to subresources (RelatedItems). While users automatically receive READ access to the NamedUserCollection, proper permissions are required to EDIT or DELETE the NamedUserCollection. Refer to the example use cases below for further clarification.

Endpoints#

PUT /itemsvc/api/v1/permissions

Parameters#

Body#

Parameter	Type	Description	Required
`_resourceDesc._irn`	String	The resource IRN, which consists of the following: `<service>:<resource type>:<resource ID>`, such as `itemsvc:nameduseritem:5cd3cd1c2ab79c0001572476`. You can also pass a pattern, such as `itemsvc:nameduseritem:*`. For more information on IRN patterns, see Look up permissions by IRN pattern.	Required
`_resourceDesc._subresourceDesc`	Object	Pass an object with `_type` and `_criteria`	Required
`_resourceDesc._subresourceDesc._type`	String	The type of subresouce. Itemservice supports `relateditem` only	Required
`_resourceDesc._subresourceDesc._criteria`	Object	A valid Item Service query criteria. The permission is applicable for the Related Items matching this criteria	Required
`_namespace`	String	The namespace that the resource belongs to	Required
`_user._type`	String	The permission user type, such as `"user"`, `"usergroup"`, or `"permprofile"`.	Required
`_user._id`	String	The permission user id.	Required
`_actions`	Array of String	The actions the user is authorized to perform on the resource, such as `"READ"`, `"CREATE"`, `"EDIT"`, `"DELETE"`, `"SHARE"` or `"*"` for all actions.	Required

Body example#

[  {    "_resourceDesc": {      "_irn": "itemsvc:nameduseritem:6333e105026300398e2d653e",      "_subresourceDesc": {        "_type": "relateditem",        "_criteria": {          "itemType": "issue"        }      }    },    "_actions": [      "READ"    ],    "_namespace": "r_TmBKvZTI",    "_user": {      "_type": "user",      "_id": "1f159053-657b-40f4-9897-434f9e2df8be"    }  }]

Response#

Response codes#

Code	Description
`200`	Success
`400`	Bad Request

Response#

{  "_success": [    {      "_resourceDesc": {        "_irn": "itemsvc:nameduseritem:6333e105026300398e2d653e",        "_subresourceDesc": {          "_type": "relateditem",          "_criteria": {            "itemType": "issue"          }        }      },      "_actions": [        "READ"      ],      "_namespace": "r_TmBKvZTI",      "_user": {        "_type": "user",        "_id": "1f159053-657b-40f4-9897-434f9e2df8be"      },      "_id": "d12dd717-6678-46e9-941d-f936d3debada"    }  ],  "_failures": []}

Example use cases for creating or updating permissions for RelatedItems#

Grant READ, EDIT, and DELETE access to specific RelatedItems#

Grant READ, EDIT, and DELETE access to specific RelatedItems within a NamedUserCollection that match the given criteria. In this case, we want RelatedItems which are categorized as pumps. However, we also want to grant only READ access, and no other permissions, to the NamedUserCollection itself.

Resource descriptor#

{  "_resourceDesc": {    "_irn": "itemsvc:nameduseritem:663112bdfbdc4b4c8b65c3d0",    "_subresourceDesc": {      "_type": "relateditem",      "_criteria": {        "dtCategory": "Pump"      }    }  },  "actions": [    "READ", "EDIT", "DELETE"  ]}

Grant CREATE RelatedItem access to the NamedUserCollection#

In this use case, we want to change permissions on the NamedUserCollection so that it can now CREATE new RelatedItems.

Resource descriptor#

{  "_resourceDesc": {    "_irn": "itemsvc:nameduseritem:663112bdfbdc4b4c8b65c3d0"  },  "actions": [    "CREATE"  ]}

Grant all access to the NamedUserCollection and RelatedItems#

In this use case, we want to grant all permissions to the specified NamedUserCollection and all RelatedItems within that collection.

Resource descriptor#

{  "_resourceDesc": {    "_irn": "itemsvc:nameduseritem:663112bdfbdc4b4c8b65c3d0"  },  "actions": [    "*"  ]}

Get Permissions#

This API call allows you to read permissions for platform resources in the Item Service, such as a NamedUserItem. The resources are specified using IRNs.

Endpoints#

GET /itemsvc/api/v1/permissions

Request#

Query parameters#

Parameter	Type	Description	Required
`_namespace`	String	The namespace where the permission is defined	Required
`_resourceDesc._irn`	String	The resource IRN, which consists of the following: `<service>:<resource type>:<resource ID>`, such as `itemsvc:nameduseritem:5cd3cd1c2ab79c0001572476`. You can also pass a pattern, such as `itemsvc:nameduseritem:*`. For more information on IRN patterns, see Look up permissions by IRN pattern.	Required
`_resourceDesc._criteria.<attribute>`	Object	Pass an object with a key-value pair for `_itemClass` or `_userType`.	Optional
`_namespace`	String	The namespace that the resource belongs to	Required
`_user._type`	String	The permission user type, such as `"user"`, `"usergroup"`, or `"permprofile"`.	Required
`_user._id`	String	The permission user id.	Optional, use current user's id if not provided
`_actions`	Array of String	The actions the user is authorized to perform on the resource, such as `"READ"`, `"CREATE"`, `"EDIT"`, `"DELETE"`, `"SHARE"` or `"*"` for all actions.	Required

Response#

Response codes#

Code	Description
`200`	Success
`400`	Bad Request

Response data example#

{  "_pageSize": 1,  "_list": [    {      "_resourceDesc": {        "_criteria": {          "_userType": "iput_cde_admin"        },        "_irn": "itemsvc:nameduseritem:*"      },      "_actions": [        "READ"      ],      "_namespace": "r_TmBKvZTI",      "_user": {        "_type": "user",        "_id": "1f159053-657b-40f4-9897-434f9e2df8be"      },      "_id": "d12dd717-6678-46e9-941d-f936d3debada",      "_status": 200    }  ],  "_offset": 0,  "_total": 1,  "_includeTotal": true}

Delete Permission by ID#

Endpoints#

DELETE /itemsvc/api/v1/permissions/{id}

Request#

Path parameters#

Parameter	Type	Description	Required
`id`	String	Pass the Permission's `_id`	Required

Response#

Response codes#

Code	Description
`204`	No Content
`404`	File Not Found

Response data#

None

Examples of permission authorization#

This section illustrates how permission authorization works by listing several examples where we use the GET, PUT, and DELETE API calls.

Example 1:#

In this example, we use the GET API call to read all RelatedItems in the collection, prioritizing the first permission as it supersedes the second.

Request#

GET /relateditems/663112bdfbdc4b4c8b65c3d0

Resource descriptors#

[  {    "_resourceDesc": {      "_irn": "itemsvc:nameduseritems:663112bdfbdc4b4c8b65c3d0"    },    "actions": [      "READ"    ]  },  {    "_resourceDesc": {      "_irn": "itemsvc:nameduseritems:663112bdfbdc4b4c8b65c3d0",      "_subresourceDesc": {        "_type": "relateditem",        "_criteria": {          "dtCategory": "Pump"        }      }    },    "actions": [      "READ"    ]  }]

Example 2:#

In this example, we use the GET API call to read only the RelatedItems that match the _subresourceDesc._criteria specified in the permission.

Request#

GET /relateditems/663112bdfbdc4b4c8b65c3d0

Resource descriptors#

[  {    "_resourceDesc": {      "_irn": "itemsvc:nameduseritems:663112bdfbdc4b4c8b65c3d0",      "_subresourceDesc": {        "_type": "relateditem",        "_criteria": {          "dtCategory": "Pump"        }      }    },    "actions": [      "READ"    ]  }]

Example 3:#

In this example, we use the GET API call to read the RelatedItems that match any of the _subresourceDesc._criteria specified in the permissions, evaluated as a union of both criteria.

Request#

GET /relateditems/663112bdfbdc4b4c8b65c3d0

Resource descriptors#

[  {    "_resourceDesc": {      "_irn": "itemsvc:nameduseritems:663112bdfbdc4b4c8b65c3d0",      "_subresourceDesc": {        "_type": "relateditem",        "_criteria": {          "dtCategory": "Pump"        }      }    },    "actions": [      "READ"    ]  },  {    "_resourceDesc": {      "_irn": "itemsvc:nameduseritems:663112bdfbdc4b4c8b65c3d0",      "_subresourceDesc": {        "_type": "relateditem",        "_criteria": {          "dtCategory": "Door"        }      }    },    "actions": [      "READ"    ]  }]

Example 4:#

Using this series of API calls, the user will be permitted to update only the RelatedItems that matches the criteria, otherwise, a 403 HTTP error will be returned.

Request#

PUT /relateditems/663112bdfbdc4b4c8b65c3d0

PUT /relateditems/

DELETE /relateditems/663112bdfbdc4b4c8b65c3d0

DELETE /relateditems/

Resource descriptors#

[  {    "_resourceDesc": {      "_irn": "itemsvc:nameduseritems:663112bdfbdc4b4c8b65c3d0",      "_subresourceDesc": {        "_type": "relateditem",        "_criteria": {          "dtCategory": "Door"        }      }    },    "actions": [      "READ", "EDIT", "DELETE"    ]  }]