Skip to main content

List permissions

Which permissions does user Sebastian have in folder Foo?

Listing permissions is a common task in any application. The Permissions Space Block provides a simple API to list all permissions, that a subject (e.g. a user) has on a resource. It lists explicitly assigned permissions as well as implicitly inherited permissions, when using a multi-level hierarchy.

Use case

Listing permissions is useful to show a list of all permissions that a user has on a resource. It can also be used in the backend, to validate permissions before executing an operation or in the frontend to show or hide UI elements based on the permissions of the current user.

Flow​

Scenario: User Bob opens the Context Menu of a file in your application. You need to check, if a certain option (e.g. "Rename file") should be visible. In this case, your Frontend can ask for a list of permissions that Bob has on that file, to craft the Context Menu UI accordingly. You should additionally double-check the permissions on your server side, to make sure the user is not able to perform actions they are not allowed to.

➊ Your Frontend asks Space Blocks directly, which permissions Bob has on file Foo

➋ Space Blocks verifies Bob’s permissions to list permissions and returns Bob’s permissions (based on which your Frontend shows or hides the “Rename file” button)

➌ In your Frontend, Bob wants to rename file Foo and sends that request to your Backend

➍ Your Backend double-checks, if Bob has the rename permission on a file with ID Foo at Space Blocks

➎ Space Blocks responds with true or false

❻ If the response it positive, your Backend renames the folder on your database

❼ You Backend returns HTTP Status code 200 (OK) or 403 (Forbidden) the your Frontend

info

For communicating directly with Space Blocks, your Frontend needs an impersonated Access Token, with should be issued by your backend.

Usage​

To list all permissions of a subject on a resource, we use the tenant's ListPermissions API.

  • /tenants/<TENANT_ID>/permissions/list

The following query parameters are required:

  • resourceType: The resource type ID
  • resourceId: The ID of the resource to check permissions on
  • subjectId: The ID of the subject to check permissions for

Example:

  • /tenants/456/permissions/list?resourceType=folder&resourceId=123&subjectId=6789

Request:

curl -i --location https://<YOUR_API_URL>/management/tenants/<TENANT_ID>/permissions/list?resourceType=<RESOURCE_TYPE>&resourceId=<RESOURCE_ID>&subjectId=<SUBJECT_ID> \
  --header "Content-Type: application/json" \
  --header "Authentication: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "apiKey: <YOUR_API_KEY>"

Example Response:

{
  "folder": ["create-files", "read"],
  "file": ["read"]
}