4.6.8. System Roles

API for working with system roles.

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

Bases: axonius_api_client.api.mixins.ModelMixins

API for working with system roles.

Examples

Parameters

auth (axonius_api_client.auth.models.Model) –

get()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

Direct API method to get all roles.

_add(name, permissions)[source]

Direct API method to add a role.

Parameters
  • name – name of new role

  • permissions – permissions for new role

_update(uuid, name, permissions)[source]

Direct API method to update a roles permissions.

Parameters
  • name – name of role to update

  • permissions – permissions to update on new role

_delete(uuid)[source]

Direct API method to delete a role.

Parameters

name – name of role to delete

_get_labels()[source]

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)[source]

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)[source]

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)[source]

Post init method for subclasses to use for extra setup.

__init__(auth, **kwargs)

Mixins for API Models.

Parameters
__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
Return type

str

_check_response_code(response, error_status=True)

Check the status code of a response.

Parameters
  • responserequests.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
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