4.6.8. System Roles

API for working with system roles.

class axonius_api_client.api.system.system_roles.SystemRoles(auth, **kwargs)

Bases: axonius_api_client.api.mixins.ModelMixins

API for working with system roles.

Examples

• Get all roles: get()

• Get a role by name: get_by_name()

• Get a role by uuid: get_by_uuid()

• Add a role: add()

• Change the name of a role: set_name()

• Change the permissions of a role: set_perms()

• Delete a role: delete_by_name()

• Get a user readable version of the permissions for a role: pretty_perms()

Parameters

auth (axonius_api_client.auth.models.Model) –

get()

Get all roles in the system.

Examples

Create a client using axonius_api_client.connect.Connect

>>> roles = client.system_roles.get()
>>> [x['name'] for x in roles]
['Admin', 'Viewer', 'Restricted', 'No Access', 'abc']

Return type

typing.List[dict]

get_by_name(name)

Get a role by name.

Examples

Create a client using axonius_api_client.connect.Connect

>>> role = client.system_roles.get_by_name(name="Admin")
>>> role["uuid"]
'5f76721bebd8d8b5459b56c8'

Parameters

name (str) – name of role to get

Raises

NotFoundError – if role not found

Return type

dict

get_by_uuid(uuid)

Get a role by uuid.

Examples

Create a client using axonius_api_client.connect.Connect

>>> role = client.system_roles.get_by_name(name="5f76721bebd8d8b5459b56c8")
>>> role["name"]
'Admin'

Parameters

uuid (str) – uuid of role to get

Raises

NotFoundError – if role not found

Return type

dict

add(name, **kwargs)

Add a role.

Examples

Create a client using axonius_api_client.connect.Connect

Create a role with the default permissions (none except dashboard view)

>>> role = client.system_roles.add(name="test1")

Create a role with specific permissions:

>>> role = client.system_roles.add(
...     name="test2", adapters="get", users_assets="get,saved_queries.run"
... )

Create a role with all permissions for all categories:

>>> role = client.system_roles.add(
...     name="test2",
...     adapters="all",
...     dashboard="all",
...     devices_assets="all",
...     enforcements="all",
...     instances="all",
...     reports="all",
...     settings="all",
...     users_assets="all",
... )

Parameters

• name (str) – name of role to add

• **kwargs – keys as categories, values as list or CSV of actions to allow for category

Raises

ApiError – if role already exists matching name

set_name(name, new_name)

Change the name of a role.

Examples

Create a client using axonius_api_client.connect.Connect

>>> role = client.system_roles.set_name(name="test1", new_name="test3")
>>> role["name"]
'test3'

Parameters

• name (str) – name of role to update

• new_name (str) – new name of role

Return type

dict

set_perms(name, grant=True, **kwargs)

Change the permissions of a role.

Examples

Create a client using axonius_api_client.connect.Connect

Add all permissions for adapters to a role

>>> role = client.system_roles.set_perms(name="test1", adapters="all")

Remove all permissions for adapters to a role

>>> role = client.system_roles.set_perms(name="test1", grant=False, adapters="all")

Add all permissions for all categories to a role:

>>> role = client.system_roles.set_perms(
...     name="test1",
...     adapters="all",
...     dashboard="all",
...     devices_assets="all",
...     enforcements="all",
...     instances="all",
...     reports="all",
...     settings="all",
...     users_assets="all",
... )

Parameters

• name (str) – name of role to update

• grant (bool) – add or remove access to the categories and actions supplied

• **kwargs – keys as categories, values as list of actions to allow for category

Return type

dict

delete_by_name(name)

Delete a role.

Examples

Create a client using axonius_api_client.connect.Connect

>>> role = client.system_roles.delete_by_name(name="test1")

Parameters

name (str) – name of role to delete

Return type

dict

pretty_perms(role)

Get a user readable version of the permissions for a role.

Examples

Create a client using axonius_api_client.connect.Connect

Pretty print a roles permission sets:

>>> print(client.system_roles.pretty_perms(role=role))
adapters             Adapters
connections.delete   Delete connection              False
connections.post     Edit connections               False
(...trimmed...)

Parameters

role (dict) – role returned from get_by_name(), get(), or get_by_uuid()

Return type

str

_get()

Direct API method to get all roles.

_add(name, permissions)

Direct API method to add a role.

Parameters

• name – name of new role

• permissions – permissions for new role

_update(uuid, name, permissions)

Direct API method to update a roles permissions.

Parameters

• name – name of role to update

• permissions – permissions to update on new role

_delete(uuid)

Direct API method to delete a role.

Parameters

name – name of role to delete

_get_labels()

Direct API method to get role labels.

property router

Router for this API model.

Return type

axonius_api_client.api.routers.Router

property cat_actions

Get permission categories and their actions.

Return type

dict

_check_predefined(role)

Check if a role is predefined.

Parameters

role (dict) – role to check

Raises

ApiError – if role is a predefined role

cat_actions_to_perms(role_perms=None, grant=True, src=None, **kwargs)

Create an updated set of role permissions based on categories and actions.

Parameters

• role_perms (typing.Optional[dict]) – permissions of a role to update

• grant (bool) – add or remove access to the actions supplied

• **kwargs – keys as categories, values as list of actions to allow for category

• src (typing.Optional[str]) –

Return type

dict

_init(**kwargs)

Post init method for subclasses to use for extra setup.

__init__(auth, **kwargs)

Mixins for API Models.

Parameters

• auth (axonius_api_client.auth.models.Model) – object to use for auth and sending API requests

• **kwargs – passed to _init()

__repr__()

Show info for this model object.

Return type

str

__str__()

Show info for this model object.

Return type

str

_build_err_msg(response, error=None, exc=None)

Build an error message from a response.

Parameters

• response (requests.Response) – response that originated the error

• error (typing.Optional[str]) – error message to include in exception

• exc (typing.Optional[Exception]) – exception that was thrown if any

Return type

str

_check_response_code(response, error_status=True)

Check the status code of a response.

Parameters

• response – requests.Response object to check

• error_status (bool) – throw exc if response status code is bad

Raises

ResponseNotOk – if response has a status code that is an error and error_status is True

_check_response_json(response, error_json_bad_status=True, error_json_invalid=True, uses_api_response=False)

Check the text body of a response is JSON.

Parameters

• response – requests.Response object to check

• error_json_bad_status (typing.Optional[bool]) – throw an exc if error key is not empty or status key == error

• error_json_invalid (typing.Optional[bool]) – throw an exc if response is invalid json

• uses_api_response (typing.Optional[bool]) –

Raises

• JsonInvalid – if error_json_invalid is True and response has invalid json

• JsonError – if error_json_bad_status is True and response is a json dict that has a non-empty error key or a status key that == error

Return type

typing.Any

request(path, method='get', raw=False, is_json=True, empty_ok=False, error_status=True, error_json_bad_status=True, error_json_invalid=True, **kwargs)

Send a REST API request.

Parameters

• path (str) – path to use in request

• method (str) – method to use in request

• raw (bool) – return the raw response object

• is_json (bool) – return the response as deserialized json or just return the text body

• error_status (bool) – throw error if response has a bad status code

• error_json_bad_status (bool) – throw error if json response has non-empty error key

• error_json_invalid (bool) – throw error if response can not be deserialized into json

• **kwargs – Passed to axonius_api_client.http.Http.__call__()

• empty_ok (bool) –

Return type

typing.Any

Returns

requests.Response or str or dict or int or list