User Group Permission Sets

This document describes API endpoints for managing User Group Permission Sets. Theirs setup is configurable at User Group level.

Endpoints for assigning users for Custom User Group Permission Set of specific User Group are described in separated document.

Permissions

Permission	Manageable via Roles	Manageable via other ways	Description
user_groups.view	true	User Group owner `view` by User Group permission sets	Allows access list
user_groups.edit_perm_set	false	User Group owner

Permissions for User Group Permission Sets can be checked by:

Context	Endpoint	Location	Available perms
Specific User Group	`GET /api/user-groups/{user_group_id}/`	`_meta.permissions`	`view`, `edit_perm_set`

User Group Permission Set types

When a User Group is created, the system automatically creates two special permission sets. The first one is automatically assigned to all standard users. The second one is automatically assigned to all group members. Request to create new User Group Permission Set with name everyone or members will be rejected. While creating User Group Permission Set, the system checks if the name is not reserved for special permission sets. Create Custom User Group Permission Set will only create a new permission set with one custom type.

To fit this requirements:

A User Group can have multiple Custom Permission Sets.
A User Group must have only one MEMBERS Permission Sets.
A User Group must have only one EVERYONE Permission Sets.

References

User Groups Permission Sets - Technical Design.

GET /api/user-groups/`user_group_id`/permission-sets/

Returns list of User Group Permission Sets for specific User Group.

Permissions

Requires authentication and user_groups.view permission.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

GET /api/user-groups/`user_group_id`/permission-sets/

Response

Key	Type	Notes
limit	int
offset	int
total_count	int	Total number of results visible to the user (based on permissions).
filtered_count	int	Number of results visible to the user (based on permissions) with filters applied.
next	url	Next page URL (null if there is no next page)
previous	url	Previous page URL (null if there is no previous page)
results	Array	List of results. Described in the next table.

Response `results` array

Key	Type	Notes
id	int
name	string
type	string	Is one of `everyone`, `members`, `custom`.
permissions	Object	Complex object containing enabled permissions for resources.
created_at	datetime
created_by	user	user (object) who created the set OR null for restricted system sets.
modified_at	datetime
modified_by	user	user (object) who last modified the set OR null for already created restricted system sets and not modified yet.

Successful status 200 OK
Response body schema

json

{
  "limit": <int>,
  "offset": <int>,
  "filtered_count": <int>,
  "total_count": <int>,
  "next": <str>,
  "previous": <str>,
  "results": [
    {
      "id": <int>,  
      "name": <str>, 
      "type": <str>,
      "permissions": {
        "user_groups": [<str>],
      },
      "created_at": <datetime>,
      "created_by": <user>,
      "modified_at": <datetime>,
      "modified_by": <user>
    }
  ]  
}

Sorting

Not available.

Filtering

Not available.

Errors

Error	Response code	Message
User Group for {user_group_id} not found.	404 Not found
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

POST /api/user-groups/`user_group_id`/permission-sets/

Creates single User Group Permission Set.

Permissions

Requires authentication and user_groups.edit_perm_sets permission.

Request

URL parameters

Key	Notes
user_group_id	User Group ID

Body parameters

Key	Type	Notes
name	string	Unique (case insensitive) for the given User Group.
permissions	Object	Optional. Complex object containing configuration for resources' permissions to be enabled.

Available resources for permissions:

user_groups

user_groups key contain list of actions. By default, permissions are disabled if not given in request's body.

Valid actions for user_groups resource:

edit
view
delete

Sent permissions are converted with dependencies described in technical doc.

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

POST /api/user-groups/'user_group_id'/permission-sets/

{
  "name": <str>, 
  "permissions": {
    "user_groups": [<str>],
  } 
}

Request example

json

{
  "name": "PermSet", 
  "permissions": {
    "user_groups": ["edit"],
  } 
}

Validations

name
- Max length: 100
- Unique: for specific User Group
- Reserved: is reserved for Special Permission Sets (e.g. owners, everyone, members)
Maximum number of User Group Permission Sets per specific User Group: 10 (includes special permission sets).

Response

Key	Type	Notes
id	int	Automatically generated by the backend.
name	string
type	string	In the POST response Only `custom` Permission Set type is displayed.
permissions	Object	Complex object contains saved permissions' configuration.
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user

Successful status 201 Created
Response body schema

json

{
  "id": <int>, 
  "name": <str>, 
  "type": <str>, 
  "permissions": {
    "user_groups": [<str>],
  }, 
  "created_at": <datetime>, 
  "created_by": <user>, 
  "modified_at": <datetime>, 
  "modified_by": <user> 
}

Errors

Error	Response code	Message
"name" is missing	400 Bad Request	"name": [ "This field is required." ]
"name" is empty string	400 Bad Request	"name": [ "This field may not be blank." ]
"name" is null	400 Bad Request	"name": [ "This field may not be null." ]
"name" has > 100 chars	400 Bad Request	"name": [ "Ensure this field has no more than 100 characters." ]
"name" is not unique for specific User Group	400 Bad Request	"name": [ "This field must be unique." ]
"name" is reserved for Special Permission Set names	400 Bad Request	"name": [ "Name \"{name}\" is reserved and cannot be used." ]
Given NULL for `permissions`	400 Bad Request	"permissions": ["This field may not be null."]
Given wrong resource name for `permissions`	400 Bad Request	"permissions": ["Invalid resource \"{given_wrong_resource_name}\"."]
Given NULL for resource in `permissions`	400 Bad Request	"permissions": {"{resource_name}": ["This field may not be null."] }
Given wrong value for resource in `permissions`	400 Bad Request	"permissions": {"{resource_name}": ["Invalid actions \"{given_wrong_value}\"."] }
Max 10 Permission Sets per user group exceeded	400 Bad Request	"detail": "Limit of 10 User Group Permission Sets has been exceeded.", "error_code": "ERR_LIMIT_EXCEEDED"
User Group with {user_group_id} does not exist	404 Not found
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

PATCH /api/user-groups/'user_group_id'/permission-sets/`id`/

Updates single User Group Permission Set.

Permissions

Requires authentication and user_groups.edit_perm_set permission.

Request

URL parameters

Key	Notes
user_group_id	User Group ID
id	UserGroup Permission Set ID

Body parameters

Key	Type	Notes
name	string	Unique (case insensitive) for the given User Group. Max length = 100 (configurable)
permissions	Object	Complex object containing configuration for resources' permissions to be enabled.

Any parameter not listed above are silently ignored if passed.

Available resource keys for permissions:

user_groups

user_groups keys contain list of actions. All are optional. If some resource is omitted then permissions for it will not be modified. Actions edit and delete cannot be set for the restricted system set Everyone.

Valid actions for resources according to type:

everyone	members	custom
view	edit view delete	edit view delete

Sent permissions are converted with dependencies described in technical doc.

⚠️ If less actions will be sent than are already in setup, not mentioned actions will be removed if they do not depend on other enabled actions.
For instance:
Current actions: ["view", "edit"]. Sent actions: ["view"]. Result actions: ["view"].

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

PATCH /api/user-groups/'user_group_id'/permission-sets/`id`/

{
  "name": <str>, 
  "permissions": {
    "user_groups": [<str>]
  } 
}

Request example

json

{
  "name": "PermSet", 
  "permissions": {
    "user_groups": ["view", "edit"]
  } 
}

Response

Key	Type	Notes
id	int
name	string
type	string	Permission Set type is displayed.
permissions	Object
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user

Successful status 200 OK
Response body schema:

json

{
  "id": <int>, 
  "name": <str>, 
  "type": <str>, 
  "permissions": {
    "user_groups": [<str>],
  },
  "created_at": <datetime>, 
  "created_by": <user>, 
  "modified_at": <datetime>, 
  "modified_by": <user> 
}

Errors

Error	Response code	Message
"name" is missing	400 Bad Request	"name": [ "This field is required." ]
"name" is empty string	400 Bad Request	"name": [ "This field may not be blank." ]
"name" is null	400 Bad Request	"name": [ "This field may not be null." ]
"name" has > 100 chars	400 Bad Request	"name": [ "Ensure this field has no more than 100 characters." ]
"name" is not unique for specific User Group	400 Bad Request	"name": [ "This field must be unique." ]
"name" is reserved for Special Permission Set names	400 Bad Request	"name": [ "Name \"{name}\" is reserved and cannot be used." ]
"name" is reserved for Special Permission Set names	400 Bad Request	"name": [ "Name \"{name}\" is reserved and cannot be used." ]
Attempt to change the name of the Special Permission Set	400 Bad Request	"name": [ "Name \"{name}\" is reserved and cannot be changed." ]
Given NULL for `permissions`	400 Bad Request	"permissions": ["This field may not be null."]
Given wrong resource name for `permissions`	400 Bad Request	"permissions": ["Invalid resource \"{given_wrong_resource_name}\"."]
Given NULL for resource in `permissions`	400 Bad Request	"permissions": {"{resource_name}": ["This field may not be null."] }
Given wrong value for resource in `permissions`	400 Bad Request	"permissions": {"{resource_name}": ["Invalid actions \"{given_wrong_value}\"."] }
Attempt to set `edit` or `delete` permissions for `Everyone` set	400 Bad Request	"permissions": {"{resource_name}": ["Invalid actions \"{given_wrong_value}\"."] }
Max 10 Permission Sets per user group exceeded	400 Bad Request	"detail": "Limit of 10 User Group Permission Sets has been exceeded.", "error_code": "ERR_LIMIT_EXCEEDED"
User Group with {user_group_id} does not exist	404 Not found
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

DELETE /api/user-groups/'user_group_id'/permission-sets/`id`/

Deletes single User Group Permission Set. Special Permission Sets cannot be deleted.

Permissions

Requires authentication and user_groups.edit_perm_sets permission.

Request

URL parameters

Key	Notes
user_group_id	User Group ID
id	User Group Permission Set ID

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

DELETE /api/user-groups/'user_group_id'/permission-sets/`id`/

Response

Successful status 204 No Content

Errors

Error	Response code	Message
User Group Permission Set with "{id}" is of type everyone	400 Bad Request	"detail": "User Group type "Everyone" is restricted and cannot be deleted."
User Group Permission Set with "{id}" is of type members	400 Bad Request	"detail": "User Group type "Members" is restricted and cannot be deleted."
User Group with "{user_group_id}" does not exist	404 Not found
User Group Permission Set with "{id}" does not exist	404 Not Found
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

OPTIONS /api/user-groups/'user_group_id'/permission-sets/

Permissions

Requires authentication only.

Request

URL parameters

Key	Notes
user_group_id	Users Group ID

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

json

OPTIONS /api/user-groups/'user_group_id'/permission-sets/

Response

Successful status 200 OK
Response body:

json

{
  "details":{
    "schema":[
      {
        "alias":"name",
        "required":true,
        "reserved":[
          "owners",
          "everyone",
          "members"
        ],
        "type":"string",
        "validators":[
          {
            "length":1,
            "type":"min_length"
          },
          {
            "length":100,
            "type":"max_length"
          }
        ]
      },
      {
        "alias":"type",
        "required":true,
        "type":"enum",
        "values":[
          {
            "system":true,
            "text":"Everyone",
            "value":"everyone"
          },
          {
            "system":true,
            "text":"Members",
            "value":"members"
          },
          {
            "system":false,
            "text":"Custom",
            "value":"custom"
          },
          {
            "system":true,
            "text":"Owners",
            "value":"owners"
          }
        ]
      },
      {
        "alias":"permissions",
        "required":false,
        "schema":[
          {
            "actions":[
              "view",
              "edit",
              "delete"
            ],
            "resource":"user_groups",
            "restrictions":[
              {
                "available":[
                  
                ],
                "default":[
                  
                ],
                "type":"owners"
              },
              {
                "available":[
                  "view"
                ],
                "default":[
                  
                ],
                "type":"everyone"
              },
              {
                "available":[
                  "view",
                  "edit",
                  "delete"
                ],
                "default":[
                  "view"
                ],
                "type":"members"
              },
              {
                "available":[
                  "view",
                  "edit",
                  "delete"
                ],
                "default":[
                  
                ],
                "type":"custom"
              }
            ]
          }
        ],
        "type":"permissions"
      }
    ]
  },
  "list":{
    "columns":[
      {
        "alias":"id",
        "predicates":[
          
        ],
        "sort_ok":false,
        "type":"int"
      },
      {
        "alias":"name",
        "predicates":[
          
        ],
        "sort_ok":false,
        "type":"string"
      },
      {
        "alias":"type",
        "predicates":[
          
        ],
        "sort_ok":false,
        "type":"enum"
      },
      {
        "alias":"permissions",
        "predicates":[
          
        ],
        "sort_ok":false,
        "type":"permissions"
      },
      {
        "alias":"created_at",
        "predicates":[
          
        ],
        "sort_ok":false,
        "type":"datetime"
      },
      {
        "alias":"created_by",
        "predicates":[
          
        ],
        "sort_ok":false,
        "type":"user"
      },
      {
        "alias":"modified_at",
        "predicates":[
          
        ],
        "sort_ok":false,
        "type":"datetime"
      },
      {
        "alias":"modified_by",
        "predicates":[
          
        ],
        "sort_ok":false,
        "type":"user"
      }
    ]
  },
  "restrictions":{
    "limit_items":10
  }
}

Errors

Error	Response code	Message
Users Group for `user_group_id` not found.	404 Not Found

Not allowed endpoints

GET /api/user-groups/'user_group_id'/permission-sets/`id`/

Response

Status 405 Method Not Allowed

User Group Permission Sets ​

Permissions ​

User Group Permission Set types ​

References ​

GET /api/user-groups/user_group_id/permission-sets/ ​

Permissions ​

Request ​

Response ​

Response results array ​

Sorting ​

Filtering ​

Errors ​

POST /api/user-groups/user_group_id/permission-sets/ ​

Permissions ​

Request ​

Validations ​

Response ​

Errors ​

PATCH /api/user-groups/'user_group_id'/permission-sets/id/ ​

Permissions ​

Request ​

Response ​

Errors ​

DELETE /api/user-groups/'user_group_id'/permission-sets/id/ ​

Permissions ​

Request ​

Response ​

Errors ​

OPTIONS /api/user-groups/'user_group_id'/permission-sets/ ​

Permissions ​

Request ​

Response ​

Errors ​

Not allowed endpoints ​

GET /api/user-groups/'user_group_id'/permission-sets/id/ ​

Response ​

User Group Permission Sets

Permissions

User Group Permission Set types

References

GET /api/user-groups/`user_group_id`/permission-sets/

Permissions

Request

Response

Response `results` array

Sorting

Filtering

Errors

POST /api/user-groups/`user_group_id`/permission-sets/

Permissions

Request

Validations

Response

Errors

PATCH /api/user-groups/'user_group_id'/permission-sets/`id`/

Permissions

Request

Response

Errors

DELETE /api/user-groups/'user_group_id'/permission-sets/`id`/

Permissions

Request

Response

Errors

OPTIONS /api/user-groups/'user_group_id'/permission-sets/

Permissions

Request

Response

Errors

Not allowed endpoints

GET /api/user-groups/'user_group_id'/permission-sets/`id`/

Response