Permission lookups
As each Permission is tied to one or more resources, the platform resource name, IRN, is the primary way to look up permissions. For more information on the IRN, see Platform resource name.
You can look up permissions by IRN or IRN pattern using either the platform APIs or the REST API.
The following page describes permission look ups by IRN and general examples and considerations for permission look ups. With this general understanding, you can learn to Look up permissions by IRN pattern.
Look up with REST API or Platform APIs#
Platform API look ups#
To look up permission using the Platform API, pass a PermissionCriteria type object which contains the following properties:
- Namespace: Pass one or more namespaces
- ResourceDescriptor: Object where you identify the resource with a pattern and optional criteria
- IRN: Pattern to target the resource
- Criteria: Optional criteria to narrow your look up
For more information, see the following example:
let criteria = { _namespace: "<your-namespace>", _resourceDesc._irn: "<irn-pattern>", _resourceDesc._criteria._<property>: "<value>" };
You can look up permissions with the following IafPermission APIs or the relevant permission APIs in a given platform service API:
- getItemPermissions
- getFilePermissions
- getDatasourcePermissions
- getObjectModelPermissions
- getPassPermissions
REST API look ups#
Add your query parameters to the following Get Permissions REST API endpoint:
GET /passportsvc/api/v1/permissions
For more information, see the following example:
/passportsvc/api/v1/permissions?_namespace=<namespace>&_resourceDesc._irn=<irn-pattern>&_resourceDesc._criteria._<property>=<value>
Permission lookup by IRN#
Use this option to get permissions with IRN patterns that cover the IRN you pass.
This option looks up IRN patterns in the database that match the text you pass. It treats the IRN you pass as text to match and looks up IRNs in the database that have matching patterns.
For more information, explore the following examples with reference these example database records:
| Database record | IRN | Actions |
|---|---|---|
| irn1 | itemsvc:nameduseritem:* | READ, EDIT |
| irn2 | itemsvc:nameduseritem:<id> | * |
| irn3 | *:*:* | READ, SHARE |
Case 1#
If the text to match is itemsvc:nameduseritem:<id>, any IRN patterns in the database that match the input text return in the results, for example itemsvc:nameduseritem:<id>, itemsvc:nameduseritem:*, and *:*:*. The permissions with these patterns cover the passed IRN.
Case 2#
If the text to match is *:*:*, any IRN patterns in the database that match the input text return in the results, which in the example records is *:*:* only. Only the permissions with this pattern covers the passed IRN.
Total actions performed#
When you look up permissions by IRN, you can also know the total actions that can be performed on the IRN based on the existing permissions.
| IRN query | By IRN results | Actions |
|---|---|---|
itemsvc:nameduseritem:* | irn1,irn3 | READ, EDIT, SHARE |
itemsvc:nameduseritem:<id> | irn1,irn2,irn3 | * |
*:*:* | irn3 | READ, SHARE |
Permission lookup examples#
Permissions for specific resource for current user#
The following example fetches permissions for the current user for a specific resource:
/passportsvc/api/v1/permissions?_namespace=NS1&_resourceDesc._irn=itemsvc:nameduseritems:63246b6cc6b43b33ef3d5e2a
Permissions for all users for a specific resource#
The following example fetches permissions for all the users for a resource:
/passportsvc/api/v1/permissions?_namespace=NS1&_resourceDesc._irn=itemsvc:nameduseritems:63246b6cc6b43b33ef3d5e2a&_user._id=*&_user._type=user
Note: The session user must have SHARE permissions to get permissions for other users. For more information, see Looking up Passport Service IRNs.
Permissions for a specific user for a specific resource#
The following example fetches permissions for a specific user for a specific resource:
/passportsvc/api/v1/permissions?_namespace=NS1&_resourceDesc._irn=itemsvc:nameduseritems:63246b6cc6b43b33ef3d5e2a&_user._id=<user_id>&_user._type=user
Note: The session user must have SHARE permissions to get permissions for another user. For more information, see Looking up Passport Service IRNs.
Note: For more information on looking up users or usergroups by id, see Looking up users or usergroups by id.
Permissions for a criteria-matching resource for the current user#
The following example fetches permissions for the current user for a specific resource specific matching criteria:
_namespace=NS1&_resourceDesc._irn=itemsvc:nameduseritems:*&_resourceDesc._criteria._userType=iaf_ext_elements
Other considerations for lookup queries#
The following example query strings demonstrate other considerations for lookup queries:
Looking up Passport Service resources#
If an IRN you want to look up is for a Passport Service resource, such as for a workspace, either the session user that initiates the lookup must have SHARE permissions or the request must come from a trusted client.
This rule applies to the following query string, for example, which returns the permissions for all the users and usergroups in a workspace:
_namespace=NS1&_namespace=NS2&_resourceDesc._irn=passportsvc:workspace:<workspace_id>&_user._id=*
Looking up users or usergroups by id#
If you want to look up users or usergroups by their specific id, you must also pass the usertype, which is either user or usergroup.
This rule applies to the following query string, for example, which returns the permissions for a specific user and the user groups they belong to and so contains the _user._type=user query parameter:
_namespace=NS1&_namespace=NS2&_resourceDesc._irn=passportsvc:workspace:<workspace_id>&_user._id=<user_id>&_user._type=user
The following query string returns the permissions for specific user group and so contains the _user._type=usergroup query parameter:
_namespace=NS1&_namespace=NS2&_resourceDesc._irn=passportsvc:workspace:<workspace_id>&_user._id=<user_group_id>&_user._type=usergroup
Look ups with or without criteria in ResourceDescription#
When you look up resources, you can specify if you want to return permission with permission criteria, without permission criteria, or both.
Criteria agnostic#
To return permissions with and without criteria, don't pass the _resourceDesc._criteria query parameter. The following example returns permissions for the current user for a given namespace and IRN, including both permissions with criteria and permission without criteria:
_namespace=NS1&_namespace=NS2&_resourceDesc._irn=filesvc:file:<file_id>
Permissions with criteria only#
To return only permissions with criteria, pass the _resourceDesc._criteria query parameter with a criteria-value pair. The following example returns permissions for the current user for a given namespaces and IRNs that match your criteria:
_namespace=NS1&_namespace=NS2&_resourceDesc._irn=filesvc:file:<file_id>&_resourceDesc._criteria.<criteria_1>=<value>
Permissions without criteria only#
To return only permissions without specified criteria, pass the _resourceDesc._criteria=null query parameter. The following example returns permissions for current user for a given namespaces and IRN but doesn't return permissions with criteria:
_namespace=NS1&_namespace=NS2&_resourceDesc._irn=filesvc:file:<file_id>&_resourceDesc._criteria=null