Granting permissions
Granting permissions
This page shows how to give a user group access to the individuals of a class, check when the access applies, and take it away again. For background, see Permissions.
The examples give a user group read and edit access to the individuals of one class. A grant on a class also covers the individuals of its subclasses. To give access to only some individuals, model them as a subclass and grant on the subclass.
Before you start, make sure you have the following:
- The ID of the class. The class must have a collection mapping, and its ontology must have a promoted version.
- The ID of the user, user group, or permission profile to grant access to.
INDIVIDUALS_SHAREand every action you plan to grant, on the class or one of its ancestors.
Every request needs an Authorization: Bearer <token> header. The examples use the namespace myapp.
Granting access to individuals
To grant access to the individuals of a class, complete the following steps:
-
Grant the actions on the class IRN. Include
INDIVIDUALS_READwithINDIVIDUALS_EDITorINDIVIDUALS_DELETE, because updates and deletes also read the individual.PUT /aosvc/api/v1/permissions?nsfilter=myapp[{"_namespace": "myapp","_resourceDesc": {"_irn": "aosvc:ontologyclass:c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa"},"_user": {"_id": "6f1e2d3c-4b5a-4978-8a1b-2c3d4e5f6a7b","_type": "usergroup"},"_actions": ["INDIVIDUALS_READ", "INDIVIDUALS_EDIT"]}]For more information, see Create or update permissions.
-
Check
_failuresin the response. If it lists an entry, read the reason, fix the entry, and send it again. -
Note the permission
_idin_success, and the task ID in theX-AOSVC-Reconciliation-Task-Idresponse header. -
Get the task until
_statusisCOMPLETED. The new access applies when the task completes.GET /aosvc/api/v1/async-tasks/{taskId}?nsfilter=myappFor more information, see Get an async task.
Note: If you map another subclass to a collection after you grant access, send the grant again to cover it.
Revoking access to individuals
To revoke access to the individuals of a class, complete the following steps:
-
Get the permission ID, if you didn't note it when you granted access.
GET /aosvc/api/v1/permissions?nsfilter=myapp&_namespace=myapp&_resourceDesc._irn=aosvc:ontologyclass:c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa&_user._id=6f1e2d3c-4b5a-4978-8a1b-2c3d4e5f6a7b&_user._type=usergroupFor more information, see Get permissions.
-
Delete the permission by its ID. Send the ID in the path, not as a query parameter.
DELETE /aosvc/api/v1/permissions/{permissionId}?nsfilter=myappFor more information, see Delete a permission.
-
Get the task named in the
X-AOSVC-Reconciliation-Task-Idresponse header until_statusisCOMPLETED. The access is removed when the task completes.