Skip to main content
Version: v5.3

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_SHARE and 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:

  1. Grant the actions on the class IRN. Include INDIVIDUALS_READ with INDIVIDUALS_EDIT or INDIVIDUALS_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.

  2. Check _failures in the response. If it lists an entry, read the reason, fix the entry, and send it again.

  3. Note the permission _id in _success, and the task ID in the X-AOSVC-Reconciliation-Task-Id response header.

  4. Get the task until _status is COMPLETED. The new access applies when the task completes.

    GET /aosvc/api/v1/async-tasks/{taskId}?nsfilter=myapp

    For 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:

  1. 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=usergroup

    For more information, see Get permissions.

  2. Delete the permission by its ID. Send the ID in the path, not as a query parameter.

    DELETE /aosvc/api/v1/permissions/{permissionId}?nsfilter=myapp

    For more information, see Delete a permission.

  3. Get the task named in the X-AOSVC-Reconciliation-Task-Id response header until _status is COMPLETED. The access is removed when the task completes.