Roles

ALX also supports commonly used roles system. Roles are simply groups (or sets) of permissions. Rather than assigning each user a permission (access) for each endpoint, he is assigned to a role. It is common that a single user is assigned to several roles. When the system needs to determine whether the given user has access to a specific endpoint, it simply loops through the user’s roles. It suffices that one role grants the user access to the given endpoint.

Hence, system administrators first define system roles and then assign these roles to individual users. This document explains technical details how this is implemented as well as the API for managing permissions.

References

Task templates

Roles API

GET /api/roles/

Retrieves the roles list.

Permissions

Requires authentication and roles.list permission.

Request example

Headers

Request Method: GET
Location: /api/roles/
Authorization: JWT access_token

Response

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

Response `results` array

Key	Type	Notes
id	uuid
name	string
description	int
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta.permissions	Object	Dict describing permissions.

Response example

Status 200 OK
Body

json

{
    "limit": 100,
    "offset": 0,
    "filtered_count": 1,
    "total_count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 15,
            "name": "Role 1",
            "description": "",
            "created_at": "2022-08-22T09:30:04.640178+02:00",
            "created_by": {
                "id": 2,
                "first_name": "John",
                "last_name": "Smith",
                "username": "j.smith@autologyx.com",
                "company_name": "Autologyx",
                "is_deleted": false,
                "account_type": "full"
            },
            "modified_at": "2022-08-22T09:45:49.582526+02:00",
            "modified_by": {
                "id": 2,
                "first_name": "John",
                "last_name": "Smith",
                "username": "j.smith@autologyx.com",
                "company_name": "Autologyx",
                "is_deleted": false,
                "account_type": "full"
            },
            "_meta": {
                "permissions": {
                    "list": true,
                    "view": true,
                    "create": true,
                    "edit": true,
                    "delete": true
                }
            }
        }
    ]
}

Sorting

Parameter	Example	Notes
id	{build}/api/roles/?ordering=id	Ascending
id	{build}/api/roles/?ordering=-id	Descending (-)
name	{build}/api/roles/?ordering=-name	Ascending (-)
name	{build}/api/roles/?ordering=-name	Descending (-)
created_at	{build}/api/roles/?ordering=created_at	Ascending
created_at	{build}/api/roles/?ordering=-created_at	Descending (-)
modified_at	{build}/api/roles/?ordering=modified_at	Ascending
modified_at	{build}/api/roles/?ordering=-modified_at	Descending (-)

Filtering

For the full description of standard predicates see ALX API standards - Developers guide.

Parameter	Predicates	Example
id	standard pk	{build}/api/object-records/?id=1
name	standard string	{build}/api/object-records/?name=Sample
created_at	standard datetime	{build}/api/object-records/?created_at__gte=2022-01-01
created_by	standard set	{build}/api/object-records/?created_by__in=123,234,345
modified_at	standard datetime	{build}/api/object-records/?modified_at__range=2022-01-01,2022-01-31
modified_by	standard set	{build}/api/object-records/?modified_by=123

Errors

Error	Response code	Message
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."

POST /api/roles/

Create new role.

Permissions

Requires authentication and superadmin permission.

URL parameters

Key	Type	Notes
name	string	Max length 80
description	string	Max length 500
permissions	Object	Available permissions

Available permissions

Resource	`list`	`view`	`create`	`edit`	`delete`	`complete`
task_templates	+	+	+	+	+
tasks	+	+		+	+	+
users	+	+
standard_authentication		+		+
object_classes	+	+	+	+	+
authentication_objects	+	+	+	+	+
company_details		+
task_group_templates	+	+	+	+	+
roles	+	+
sequences	+	+	+	+	+
single_sign_on	+	+	+	+	+
user_groups			+
message_templates	+
object_models	+	+	+	+

Request example

Headers

Request Method: POST
Location: /api/roles/
Authorization: JWT access_token

Body

json

{
  "name": "Sample Role",
  "description": "Sample description",
  "permissions": {
    "task_template": [
      "list",
      "create",
      "view",
      "edit",
      "delete"
    ]
  }
}

Response

Key	Type	Notes
id	int
name	string
description	int
num_of_users	enum
permissions	bool
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta.permissions	Object	Object describing permissions

Response example

Status 201 CREATED
Body

json

{
  "id": 10,
  "name": "Sample Role",
  "description": "Sample description",
  "num_of_users": 0,
  "permissions": {
    "task_group": [
      "list",
      "create",
      "view",
      "edit",
      "delete"
    ]
  },
  "created_by": {
    "id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "username": "j.smith@autologyx.com",
    "company_name": "Autologyx",
    "is_deleted": false
  },
  "modified_by": {
    "id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "username": "j.smith@autologyx.com",
    "company_name": "Autologyx",
    "is_deleted": false
  },
  "created_at": "2020-05-06T10:21:30.751914Z",
  "modified_at": "2020-05-06T10:21:30.751914Z",
  "_meta": {
    "permissions": {
      "list": true,
      "view": true,
      "edit": true,
      "create": true,
      "delete": true
    }
  }
}

Errors

Error	Response code	Message
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."

GET /api/roles/`id`/

Retrieve the role.

Permissions

Requires authentication and roles.view permission.

Request example

Headers

Request Method: GET
Location: /api/roles/1/
Authorization: JWT access_token

Response

Key	Type	Notes
id	int
name	string
description	int
num_of_users	enum
permissions	bool
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta.permissions	Object	Object describing permissions

Response example

Status 200 OK
Body

json

{
  "id": 10,
  "name": "Sample Role",
  "description": "Sample description",
  "num_of_users": 0,
  "permissions": {
    "task_group": [
      "list",
      "create",
      "view",
      "edit",
      "delete"
    ]
  },
  "created_by": {
    "id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "username": "j.smith@autologyx.com",
    "company_name": "Autologyx",
    "is_deleted": false
  },
  "modified_by": {
    "id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "username": "j.smith@autologyx.com",
    "company_name": "Autologyx",
    "is_deleted": false
  },
  "created_at": "2020-05-06T10:21:30.751914Z",
  "modified_at": "2020-05-06T10:21:30.751914Z",
  "_meta": {
    "permissions": {
      "list": true,
      "view": true,
      "edit": true,
      "create": true,
      "delete": true
    }
  }
}

PATCH /api/roles/`id`/

Update the role.

Permissions

Requires authentication and superadmin permission.

Allowed parameters

Key	Type	Notes
name	string	Max length 80
description	string	Max length 500
permissions	Object	Available permissions

Any parameter not listed above are silently ignored if passed.

Request example

Headers

Request Method: PATCH
Location: /api/roles/1/
Authorization: JWT access_token

Body

json

{
  "name": "Sample Role",
  "description": "Sample description",
  "permissions": {
    "task_template": [
      "list",
      "create",
      "view",
      "edit",
      "delete"
    ]
  }
}

Response

Key	Type	Notes
id	int
name	string
description	int
num_of_users	enum
permissions	bool
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
_meta.permissions	Object	Object describing permissions

Response example

Status 200 OK
Body

json

{
  "id": 10,
  "name": "Sample Role",
  "description": "Sample description",
  "num_of_users": 0,
  "permissions": {
    "task_group": [
      "list",
      "create",
      "view",
      "edit",
      "delete"
    ]
  },
  "created_by": {
    "id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "username": "j.smith@autologyx.com",
    "company_name": "Autologyx",
    "is_deleted": false
  },
  "modified_by": {
    "id": 1,
    "first_name": "John",
    "last_name": "Smith",
    "username": "j.smith@autologyx.com",
    "company_name": "Autologyx",
    "is_deleted": false
  },
  "created_at": "2020-05-06T10:21:30.751914Z",
  "modified_at": "2020-05-06T10:21:30.751914Z",
  "_meta": {
    "permissions": {
      "list": true,
      "view": true,
      "edit": true,
      "create": true,
      "delete": true
    }
  }
}

Errors

Error	Response code	Message
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."

OPTIONS /api/roles/

Permissions

Requires authentication only.

Request example

Headers

Request Method: OPTIONS
Location: /api/roles/

Response example

Status 200 OK
Body

json

{
  "list": {
    "columns": [
      {
        "alias": "id",
        "type": "int",
        "predicates": [
          "exact",
          "gt",
          "gte",
          "lt",
          "lte",
          "range"
        ],
        "sort_ok": true
      },
      {
        "alias": "name",
        "type": "string",
        "predicates": [
          "exact",
          "iexact",
          "contains",
          "icontains",
          "startswith",
          "istartswith",
          "endswith",
          "iendswith"
        ],
        "sort_ok": true
      },
      {
        "alias": "description",
        "type": "string",
        "predicates": [],
        "sort_ok": false
      },
      {
        "alias": "created_at",
        "type": "datetime",
        "predicates": [
          "exact",
          "gt",
          "gte",
          "lt",
          "lte",
          "range"
        ],
        "sort_ok": true
      },
      {
        "alias": "created_by",
        "type": "user",
        "predicates": [
          "exact",
          "in"
        ],
        "sort_ok": false,
        "autocomplete": "/api/users/autocomplete/?text__icontains="
      },
      {
        "alias": "modified_at",
        "type": "datetime",
        "predicates": [
          "exact",
          "gt",
          "gte",
          "lt",
          "lte",
          "range"
        ],
        "sort_ok": true
      },
      {
        "alias": "modified_by",
        "type": "user",
        "predicates": [
          "exact",
          "in"
        ],
        "sort_ok": false,
        "autocomplete": "/api/users/autocomplete/?text__icontains="
      }
    ]
  },
  "details": {
    "schema": [
      {
        "alias": "name",
        "type": "string",
        "required": true,
        "validators": [
          {
            "type": "max_length",
            "length": 80
          }
        ]
      },
      {
        "alias": "description",
        "type": "string",
        "required": false,
        "validators": [
          {
            "type": "max_length",
            "length": 500
          }
        ]
      },
      {
        "alias": "permissions",
        "type": "permissions",
        "required": false,
        "schema": [
          {
            "resource": "task_templates",
            "actions": [
              "list",
              "view",
              "create",
              "edit",
              "delete"
            ]
          },
          {
            "resource": "tasks",
            "actions": [
              "list",
              "view",
              "edit",
              "complete"
            ]
          },
          {
            "resource": "users",
            "actions": [
              "list",
              "view"
            ]
          },
          {
            "resource": "standard_authentication",
            "actions": [
              "view",
              "edit"
            ]
          },
          {
            "resource": "object_classes",
            "actions": [
              "list",
              "view",
              "create",
              "edit",
              "delete"
            ]
          },
          {
            "resource": "authentication_objects",
            "actions": [
              "list",
              "view",
              "create",
              "edit",
              "delete"
            ]
          },
          {
            "resource": "company_details",
            "actions": [
              "edit",
              "view"
            ]
          },
          {
            "resource": "task_group_templates",
            "actions": [
              "list",
              "view",
              "create",
              "edit"
            ]
          },
          {
            "resource": "roles",
            "actions": [
              "list",
              "view"
            ]
          },
          {
            "resource": "sequences",
            "actions": [
              "list",
              "view",
              "create",
              "edit",
              "delete"
            ]
          },
          {
            "resource": "single_sign_on",
            "actions": [
              "list",
              "view",
              "create",
              "edit",
              "delete"
            ]
          },
          {
            "resource": "user_groups",
            "actions": [
              "create"
            ]
          },
          {
            "resource": "message_templates",
            "actions": [
              "list"
            ]
          },
          {
            "resource": "object_models",
            "actions": [
              "list",
              "view",
              "create",
              "edit"
            ]
          }
        ]
      }
    ]
  },
  "restrictions": {
    "limit_items": 5000
  }
}

Roles ​

References ​

Roles API ​

GET /api/roles/ ​

Permissions ​

Request example ​

Response ​

Response results array ​

Response example ​

Sorting ​

Filtering ​

Errors ​

POST /api/roles/ ​

Permissions ​

URL parameters ​

Available permissions ​

Request example ​

Response ​

Response example ​

Errors ​

GET /api/roles/id/ ​

Permissions ​

Request example ​

Response ​

Response example ​

PATCH /api/roles/id/ ​

Permissions ​

Allowed parameters ​

Request example ​

Response ​

Response example ​

Errors ​

OPTIONS /api/roles/ ​

Permissions ​

Request example ​

Response example ​

Roles

References

Roles API

GET /api/roles/

Permissions

Request example

Response

Response `results` array

Response example

Sorting

Filtering

Errors

POST /api/roles/

Permissions

URL parameters

Available permissions

Request example

Response

Response example

Errors

GET /api/roles/`id`/

Permissions

Request example

Response

Response example

PATCH /api/roles/`id`/

Permissions

Allowed parameters

Request example

Response

Response example

Errors

OPTIONS /api/roles/

Permissions

Request example

Response example