Control API reference

RADKit Control will allow you to programmatically retrieve, modify and update RADKit service components. That is, if you have a running RADKit Service, RADKit Control can make it manageable over the network, as an alternative to the WebUI.

RADKit Control provides two different interfaces - a CLI and a Python API. The goal of this document is to describe RADKit Control Python API and show you how you might use it. For details on the Control CLI, see Control CLI.

When you are done here, you will be able to use RADKit API to have control over the components below individually and in bulk:

Devices, remote users, labels, admins, and roles can be managed (added, updated, deleted).
The Service itself can be managed.

We are exposing now a ControlAPI which wraps AsyncControlAPI and exposes same set of methods but synchronous. All the API calls are happening in a dedicated thread where event loop is running.

The purpose of this design is to provide a more familiar and straightforward programming model for users who are more comfortable with synchronous programming.

Note

Much of RADKit Control power comes from following a Pydantic model. When data is validated against a Pydantic model, if any errors or inconsistencies are detected, Pydantic raises detailed validation errors that clearly indicate the problems and their locations.

Note

Some functions require a component id or uuid, if you are not sure about any user, device, label, or role identifier for carrying out a certain operation, list function and its cli equivalent can show you the needed ids.

Warning

Avoid hardcoding device types (e.g. “IOS_XE”, “ISE” etc.). Instead use DeviceType.IOS_XE, DeviceType.ISE, … .

Before getting started, to disable TLS verification using ControlAPI please follow the example below:

#!/usr/bin/env python

from getpass import getpass

from radkit_service.control_api import ControlAPI

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: "),
    http_client_kwargs=dict(verify=False),
) as service:
    ...

User operations 

Includes listing, creation, update, delete also in bulk with JSON and CSV support.

Note

You might come across CustomSecretStr From an external point of view, this is a plain string password for users login. CustomSecretStr internally wraps this String so passwords are never leaked.

Warning

Combining create, update, delete in the same JSON or CSV is not supported. Users are invited to split their files in order to run different operations separately. This also applies to optional fields.

ControlAPI.get_remote_user( username: str, ) → APIResult[list[StoredRemoteUser]]

Get all the information stored on RADKit Service for a certain remote user.

Parameters:: username – The username of the remote user you are interested in.
Returns:: APIResult object, which is a list of StoredRemoteUser (see Remote users) objects for more information.

ControlAPI.list_remote_users() → APIResult[list[StoredRemoteUser]]

List all the remote users existing on the RADKit service.

Returns:: a list of StoredRemote user objects (see Remote users). Each user is represented by a dictionary with all the user attributes.

ControlAPI.create_remote_user( user: NewRemoteUser, ) → APIResult[StoredRemoteUser]

Create a new remote user on the RADKit service. Validated against NewRemoteUser model (see Remote users).

Parameters:: user – A NewRemoteUser object representing the attributes of the remote user (see Remote users).
Returns:: APIResult containing the created StoredRemoteUser (see Remote users).

ControlAPI.create_remote_users( users: Sequence[NewRemoteUser], ) → BulkResult[StoredRemoteUser]

Create multiple users.

Parameters:: users – A sequence of NewRemoteUser objects representing the attributes of the remote users (see Remote users).
Returns:: BulkResult[StoredRemoteUser]: The result of the bulk API call, containing a list of created StoredRemoteUser objects (see Remote users).

ControlAPI.update_remote_user( user: UpdateRemoteUser, ) → APIResult[StoredRemoteUser]

Update an existing remote user (see Remote users).

Parameters:: user – An UpdateRemoteUser object representing the changes to be made to the remote user (see Remote users).
Returns:: APIResult containing the updated StoredRemoteUser (see Remote users).

ControlAPI.update_remote_users( users: Sequence[UpdateRemoteUser], ) → BulkResult[StoredRemoteUser]

The method first performs some sanity checks on the parameters to ensure they are valid (see Remote users). Then it will have radkit-control update multiple users’ attributes based on the parameters passed identified by username.

Parameters:: users – A sequence of UpdateRemoteUser objects representing the changes for each remote user (see Remote users).
Returns:: BulkResult The result of the bulk API call, containing updated StoredRemoteUser objects (see Remote users).

ControlAPI.delete_remote_user( username: str, ) → APIResult[str]

Delete a specific remote user on the RADKit service identified by the username.

Parameters:: username – The String username of the remote user to be deleted.
Returns:: APIResult[str] to show how the operation went.

ControlAPI.delete_remote_users( usernames: Collection[str], ) → BulkResult[str]

Delete multiple users based on a given iterable.

Parameters:: usernames – A collection of usernames to delete as strings.
Returns:: BulkResult[str] resembling how the operation went.

Device operations

Includes listing, creation, update, delete also in bulk with JSON and CSV support.

Note

You might come across CustomSecretStr From an external point of view, this is a plain string password for credentials. CustomSecretStr internally wraps this String so passwords are never leaked.

Warning

Combining create, update, delete in the same JSON or CSV is not supported. Users are invited to split their files in order to run different operations separately. This also applies to optional fields.

ControlAPI.list_devices( exclude_metadata: bool = False, ) → APIResult[list[StoredDevice[Annotated[UUID, UuidVersion], int]]]

List all the devices existing on the RADKit service with their associated parameters.

Parameters:: exclude_metadata – If True, don’t include the metadata field in the response.
Returns:: A list of all StoredDevice objects (see Devices). Each entry is a dictionary containing all the device details (name, management ip address, configured protocols, activation status,…etc)

ControlAPI.get_device( device_uuid: str, ) → APIResult[list[StoredDevice[Annotated[UUID, UuidVersion], int]]]

Get a device existing on the RADKit service with its associated parameters identified by its UUID.

Parameters:: device_uuid – unique identifier for the device as a string.
Returns:: A list of all StoredDevice objects (see Devices) containing all the device details (name, management ip address, configured protocols, activation status,…etc).

ControlAPI.create_device( device: NewDevice, ) → APIResult[StoredDevice[Annotated[UUID, UuidVersion], int]]

Create a new device on the RADKit service. Your input is validated with pydantic model and clear error messages are shown if there is a validation error.

Parameters:: device – Takes a NewDevice object. From NewDevice object parameters see (see Devices).
Returns:: [StoredDevice]: The result of the bulk API call, containing the device created in the form StoredDevice object. (see Devices).

ControlAPI.create_devices( devices: Sequence[NewDevice], ) → BulkResult[StoredDevice[Annotated[UUID, UuidVersion], int]]

Create multiple devices on the service.

Parameters:: devices – A sequence of NewDevice objects: representing the devices to create. (see Devices).
Returns:: [StoredDevice] bulk result. (see Devices).

ControlAPI.update_device( device: UpdateDevice, ) → APIResult[StoredDevice[Annotated[UUID, UuidVersion], int]]

Update a device with all the parameters specified in the device dictionary. Any parameter which is not updated will remain as it is.

Parameters:: device – Takes a UpdateDevice object to understand more on what it expects (see Devices).
Returns:: [StoredDevice]: The result of the bulk API call, containing a StoredDevice object. (see Devices)

ControlAPI.update_devices( devices: Sequence[UpdateDevice], ) → BulkResult[StoredDevice[Annotated[UUID, UuidVersion], int]]

Update multiple devices with all the parameters specified in the device dictionary. Any parameter which is not updated will remain as it is.

Parameters:: devices – A sequence of UpdateDevice objects (see Devices) to understand more on what it expects (see Devices).
Returns:: [StoredDevice]: The result of the bulk API call, containing a StoredDevice object. (see Devices)

ControlAPI.delete_device( device_uuid: Annotated[UUID, UuidVersion(uuid_version=4)] | str, ) → APIResult[Annotated[UUID, UuidVersion]]

Delete a certain device existing on the RADKit service identified by its UUID.

Parameters:: device_uuid – string unique identifier for the device.
Returns:: API call result.

ControlAPI.delete_devices( device_ids: Collection[Annotated[UUID, UuidVersion(uuid_version=4)]], ) → BulkResult[Annotated[UUID, UuidVersion]]

Delete multiple devices existing on the RADKit service identified by their UUID.

Parameters:: device_ids – A collection of UUIDs of the devices to delete.
Returns:: Bulk result object containing a list of UUID4 values.

ControlAPI.import_devices( device_uuid: Annotated[UUID, UuidVersion(uuid_version=4)] | str, tag: str | None = None, ) → APIResult[int]

Import and/or synchronize devices from external source.

Parameters:: device_uuid – UUID of the device to import devices from
Returns:: number of processed devices

ControlAPI.list_device_types() → APIResult[dict[DeviceType, str]]: List device types id to display name.

Example script that uses get_device and update_device:

#!/usr/bin/env python

from getpass import getpass
from time import time

from radkit_service.control_api import ControlAPI

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    print("Getting device list")
    devices = service.list_devices().get_result()

    devices = [device for device in devices if "test-device-" in device.name]

    print(f"Identified {len(devices)} devices")

    now = time()
    new_description = f"modified {now}"
    update_devices = []
    for device in devices:
        update_devices.append(
            UpdateDevice(uuid=device.uuid, description=new_description)
        )

    print("Sending to RADKit Service")
    service.update_devices(update_devices)

Example script that uses metadata in NewDevice creation:

#!/usr/bin/env python

from getpass import getpass
from math import floor

from radkit_common.utils.formatting import to_canonical_name
from radkit_common.utils.ssl import create_public_ssl_context
from radkit_common.types import DeviceType
from radkit_service.control_api import ControlAPI
from radkit_service.webserver.models.devices import MetaDataEntry, NewDevice, NewTerminal

from stopwatch import StopWatch

password = getpass()

verify = create_public_ssl_context(verify=False, use_obsolete_ciphers=False)

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=password,
    http_client_kwargs=dict(verify=verify)
) as service:
    stopwatch = StopWatch()

    devices = []
    for i in range(20000):
        hostname = f"new test-device_{i}"
        canonical_name = to_canonical_name(hostname)
        terminal = NewTerminal(
            username="admin",
            password="Cisco123",
        )
        metadata = [
            MetaDataEntry(key="original-hostname", value=hostname),
            MetaDataEntry(key="index", value=str(i))
        ]
        device = NewDevice(
            name=canonical_name,
            host=f"2.{floor(i/(256*256))}.{floor(i/256)}.{i%256}",
            deviceType=DeviceType.IOS_XE,
            terminal=terminal,
            metaData=metadata,
            enabled=True,
        )
        devices.append(device)

    print(f"creating {len(devices)} devices")
    stopwatch.start()
    result = service.create_devices(devices)
    stopwatch.stop()
    stopwatch.print_delta(f"devices created in ")

Note

In the example above, we used to_canonical_name() function that transforms a random name into a name RADKit can accept.

Label operations 

Includes listing, creation, update, delete also in bulk with JSON and CSV support.

Warning

Combining create, update, delete in the same JSON or CSV is not supported. Users are invited to split their files in order to run different operations separately. This also applies to optional fields.

ControlAPI.list_labels( *, scope: Literal['rbac', 'context', 'all'] = 'rbac', ) → APIResult[list[StoredLabel]]

List labels existing on the RADKit service.

Parameters:: scope – Labels scope filter. One of: rbac (default), context, all.
Returns:: A list of StoredLabel objects (see Labels) the device access labels known by this RADKit Service.

ControlAPI.create_labels( labels: Sequence[NewLabel], ) → BulkResult[StoredLabel]

Create multiple labels on RADKit service.

Parameters:: labels – A sequence of NewLabel objects. (see Labels) for NewLabel attributes.
Returns:: [StoredLabel]: The result of the API call, containing a StoredLabel object. (see Labels)

ControlAPI.update_labels( labels: Sequence[UpdateLabel], ) → BulkResult[StoredLabel]

Update multiple labels on RADKit service. Anything you do not specify will default to not be updated.

Parameters:: labels – A sequence of UpdateLabel objects. (see Labels)
Returns:: [StoredLabel]: The result of the API call, containing a StoredLabel object. (see Labels)

Note

list_labels and its cli equivalent can show you the label ids.

ControlAPI.delete_labels( label_ids: Collection[int], ) → BulkResult[StoredLabel]

Delete multiple labels on the RADKit service identified by their id.

Parameters:: label_ids – A collection of label IDs to delete as integers.
Returns:: [StoredLabel]: The result of the API call, containing a StoredLabel object. (see Labels)

Note

list_labels and its cli equivalent can show you the label ids.

Returns:: BulkResult[StoredLabel]: The bulk result containing a StoredLabel object. (see Labels)

Admin operations 

Includes listing, creation, update, delete also in bulk with JSON and CSV support.

Note

You might come across CustomSecretStr From an external point of view, this is a plain string password for admin login. CustomSecretStr internally wraps this String so passwords are never leaked.

Warning

Combining create, update, delete in the same JSON or CSV is not supported. Users are invited to split their files in order to run different operations separately. This also applies to optional fields.

ControlAPI.list_admins() → APIResult[list[StoredAdmin]]

List all admins on a RADKit service.

Returns:: a list of all StoredAdmin objects. Each user is represented by a dictionary with all the user attributes. (see Remote users)

ControlAPI.get_admin( admin_name: str, ) → APIResult[list[StoredAdmin]]

Get a certain admin details identified by the admin name.

Parameters:: admin_name – String of the admin name.
Returns:: StoredAdmin object with details like username, email, fullname and description of this chosen admin. (see Remote users)

ControlAPI.create_admin( admin: NewAdmin, ) → APIResult[StoredAdmin]

Create an admin user. Must be done before any other command can be executed. Takes a user name and a password as argument. If “initial” is True, consider this user as the very first admin user. This causes the request to NOT be authenticated and only works if this is truly the first user in the system. (see Remote users)

Parameters:: admin – A NewAdmin object representing the attributes of the admin to create (see Remote users).
Returns:: APIResult[StoredAdmin] (see Remote users)

ControlAPI.create_admins( admins: Sequence[NewAdmin], ) → BulkResult[StoredAdmin]

Create multiple admins with all the parameters specified in the admin dictionary.

Parameters:: admins – A sequence of NewAdmin objects. Check the parameters above for NewAdmin attributes.
Returns:: BulkResult[StoredAdmin] (see Remote users)

ControlAPI.update_admin( admin: UpdateAdmin, ) → APIResult[StoredAdmin]

Update a certain admin identified by its admin name.

Parameters:: admin – An UpdateAdmin object representing the changes to be made to the admin (see Remote users).
Returns:: The result of the API call, containing the updated StoredAdmin object. (see Remote users)

Note

There is no password update and no admin_name update for an Admin using update through Control.

ControlAPI.update_admins( admins: Sequence[UpdateAdmin], ) → BulkResult[StoredAdmin]

Update multiple admins with various attributes.

Parameters:: admins – A sequence of UpdateAdmin objects representing the attributes of the admins. (see Remote users).
Returns:: The result of the API call, containing the updated StoredAdmin objects in bulk. (see Remote users).

ControlAPI.delete_admin( admin_name: str, ) → APIResult[str]

Delete an admin user at your own risk.

Parameters:: admin_name – String with the name of admin to be deleted.
Returns:: Result of API call as a string.

ControlAPI.delete_admins( usernames: Collection[str], ) → BulkResult[str]

Delete multiple admins.

Parameters:: usernames – A collection of admin_names to delete as strings.
Returns:: Bulk result API call as strings.

ControlAPI.change_password( username: str, new_password: CustomSecretStr, old_password: CustomSecretStr, ) → APIResult[StoredAdmin]

Change an admin user’s password. Takes a username, old password, and new password as arguments. (see Remote users)

Parameters:

username – String representing the username.
old_password – String representing the old password.
new_password – String representing the new password. The password must meet the following criteria: at least 8 characters, 1 lowercase letter, 1 uppercase letter, 1 digit, and 1 symbol.

Returns:

APIResult[StoredAdmin] (see Remote users)

Role operations 

Includes listing, creation, update, delete of roles individually.

Note

Roles define sets of permissions (claims) that can be assigned to administrators. Each role contains a name, description, and a set of claims that define what actions the role allows.

Warning

System administrator roles (isSysadmin=True) have full access to all operations and cannot be restricted by individual claims.

ControlAPI.list_roles() → APIResult[list[StoredRole]]

List all roles.

Returns:: API result containing list of stored roles.

ControlAPI.create_role( role: NewRole, ) → APIResult[StoredRole]

Create a new role.

Parameters:: role – A NewRole object representing the attributes of the role to create (see Roles).
Returns:: API result containing the created role.

ControlAPI.update_role( role: UpdateRole, ) → APIResult[StoredRole]

Update an existing role.

Parameters:: role – An UpdateRole object representing the changes to be made to the role (see Roles).
Returns:: API result containing the updated role.

ControlAPI.delete_role( role_id: int, ) → APIResult[StoredRole]

Delete a role.

Parameters:: role_id – The ID of the role to delete.
Returns:: API result containing deletion confirmation.

Example script that creates a role with specific claims:

#!/usr/bin/env python

from getpass import getpass

from radkit_service.control_api import *

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
) as service:
    # Create a role for device administrators
    role_result = service.create_role(
        name="device-admin",
        description="Role for managing devices",
        claims={Claim.READ_DEVICES, Claim.MODIFY_DEVICES}
    )

    if role_result.success:
        print(f"Created role: {role_result.result.name}")
    else:
        print(f"Failed to create role: {role_result.error}")

Service operations 

Includes initial bootstrap, enroll, get_service_status, stop, reset, get version, settings.

ControlAPI.init_bootstrap_admin( password: CustomSecretStr, ) → APIResult[StoredAdmin]: Get up the very first admin user. Must be done before any other command can be executed. Takes a user name and a password as argument.

Note

No authentication required for this API, obviously since we are creating the first admin user.

ControlAPI.enroll_service( otp: str, timeout: int = 30, ) → APIResult[str]

Enroll the service.

Parameters:

otp – The One-Time Password string.
timeout – An optional parameter of type int with a default value of 30. It represents the timeout duration in seconds for the enrollment process. If no value is provided when calling the function, it will default to 30.

Returns:

The result of the enrollment process, containing the enrollment status and any associated data.

ControlAPI.get_service_status() → APIResult[Status]: Get the RADKit Service status.

ControlAPI.stop_service() → APIResult[str]: Stop the service when there is superadmin user created already.

ControlAPI.stop_service_unauthenticated() → APIResult[str]: Stop the service when there is no superadmin user created yet.

ControlAPI.get_service_version() → APIResult[str]: Get the version of the running service.

ControlAPI.system_reset_service() → APIResult[str]: Remove serial number file and client certificates.

ControlAPI.set_settings( settings: Sequence[SettingChange], ) → BulkResult[APISettingInfo]

Set the settings for the service. (see Settings)

Returns:: The result of the API call, the list of Setting object (see Settings).

ControlAPI.get_settings( settings: Collection[str] = (), ui_visible: bool = False, ) → APIResult[list[APISettingInfo]]

Retrieve the current settings of the RADKit service.

Returns:: The result of the API call, containing the service settings as a dictionary (see Settings).

Data types 

In RADKit ControlAPI functions you will encounter objects that are either returned or taken as parameters mostly for data validation purposes. In this section, we will explain the users, devices, labels, roles and settings models:

Remote users 

Represents the Remote User model which includes representation of remote user data used for ControlAPI functions in separate classes depending on the kind of operation.

pydantic model radkit_service.control_api.StoredRemoteUser

Bases: RADKitBaseModel

Data model for an existing remote user. See NewRemoteUser for more information about the fields listed below.

field username: str [Required]

field fullname: str [Required]

field description: str [Required]

field time_slice_minutes: PositiveInt | None = None (alias 'timeSliceMinutes')

field expiration_timestamp: AwareDatetime | None = None (alias 'expirationTimestamp')

field labels: Set[int] [Required]

field access_token: AnnotatedCustomSecretStr = CustomSecretStr('') (alias 'accessToken')

Constraints:

func = <function <lambda> at 0x7f0bbd684c20>
return_type = <class ‘str’>
when_used = always
json_schema = {‘type’: ‘string’}
mode = serialization

field connection_mode_cloud_active: bool [Required] (alias 'connectionModeCloudActive'): Specifies if given user can connect to the service through the cloud.

field connection_mode_direct_active: bool [Required] (alias 'connectionModeDirectActive'): Specifies if given user can connect to the service directly.

field connection_mode_direct_sso_active: bool [Required] (alias 'connectionModeDirectSsoActive'): Specifies if given user can connect to the service directly with the identity confirmed by the cloud.

field external_auth: StoredExternalAuth | None = None (alias 'externalAuth')

External authentication configuration.

classmethod from_db_user( encryptor: DbSecretsEncryptor, user: DbRemoteUser, ) → StoredRemoteUser: Convert DbRemoteUser to StoredRemoteUser instance.

pydantic model radkit_service.control_api.NewRemoteUser

Bases: RADKitBaseModel

Data model for creating a new remote user.

field username: EmailStr [Required]: The remote user’s email address.

field fullname: str [Required]: The remote user’s full name.

field description: str [Required]: The remote user’s description.

field time_slice_minutes: PositiveInt | None = None (alias 'timeSliceMinutes'): Optional. The duration in minutes that the remote user can be granted remote access for. After this time is expired, the user will be automatically disabled. If this field is omitted, remote access will have to be managed manually by enabling/disabling the user.

field expiration_timestamp: Annotated[AwareDatetime | None, AfterValidator(ensure_utc)] = None (alias 'expirationTimestamp')

Optional. The absolute time at which the user’s remote access will be revoked.

Constraints:

func = <function ensure_utc at 0x7f0bbc82ac00>

field labels: Sequence[int | str] [Optional]: Optional. A sequence of integers or strings representing the labels associated with the remote user.

field access_token: CustomSecretStr | None = None (alias 'accessToken')

Optional. Access token for E2EE session verification. An access token will automatically be generated if none was given.

Validated by:

validate_access_token

field connection_mode_cloud_active: bool = True (alias 'connectionModeCloudActive'): Specifies if given user can connect to the service through the cloud.

field connection_mode_direct_active: bool = True (alias 'connectionModeDirectActive'): Specifies if given user can connect to the service directly.

field connection_mode_direct_sso_active: bool = True (alias 'connectionModeDirectSsoActive'): Specifies if given user can connect to the service directly with the identity confirmed by the cloud.

field external_auth: NewExternalAuth | None = None (alias 'externalAuth'): External authentication configuration.

pydantic model radkit_service.control_api.NewRemoteUsers

Bases: RADKitRootModel[list[NewRemoteUser]]

A list of NewRemoteUser entries for bulk remote user creation.

field root: list[NewRemoteUser] [Required]

Constraints:

max_length = 1000

pydantic model radkit_service.control_api.UpdateRemoteUser

Bases: RADKitBaseModel

Data model for updating an existing remote user entry. See NewRemoteUser for more information about the fields listed below.

field username: EmailStr [Required]: The current email address for the remote user.

field new_username: UpdateField[EmailStr] = DontUpdate(dontUpdate=True) (alias 'newUsername'): Optional. The new email address for the remote user, if the user is to be renamed.

field fullname: UpdateField[str] = DontUpdate(dontUpdate=True)

field description: UpdateField[str] = DontUpdate(dontUpdate=True)

field expiration_timestamp: UpdateField[Annotated[AwareDatetime | None, AfterValidator(ensure_utc)] | None] = DontUpdate(dontUpdate=True) (alias 'expirationTimestamp'): Optional. The new absolute expiration time for the remote user.

field time_slice_minutes: UpdateField[PositiveInt | None] = DontUpdate(dontUpdate=True) (alias 'timeSliceMinutes'): Optional. The new time slice in minutes for the remote user.

field label_update: UpdateLabelSet [Optional] (alias 'labelUpdate'): Optional. The labels to be added/removed/replaced on the remote users, as integers or strings. See UpdateLabelSet for details.

field access_token: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True) (alias 'accessToken')

Optional. The new access token for E2EE session verification. An access token will automatically be generated if none was given.

Validated by:

validate_access_token

field connection_mode_cloud_active: UpdateField[bool] = DontUpdate(dontUpdate=True) (alias 'connectionModeCloudActive'): Specifies if given user can connect to the service through the cloud.

field connection_mode_direct_active: UpdateField[bool] = DontUpdate(dontUpdate=True) (alias 'connectionModeDirectActive'): Specifies if given user can connect to the service directly.

field connection_mode_direct_sso_active: UpdateField[bool] = DontUpdate(dontUpdate=True) (alias 'connectionModeDirectSsoActive'): Specifies if given user can connect to the service directly with the identity confirmed by the cloud.

field external_auth: UpdateField[UpdateExternalAuth | None] = DontUpdate(dontUpdate=True) (alias 'externalAuth'): External authentication configuration.

pydantic model radkit_service.control_api.UpdateRemoteUsers

Bases: RADKitRootModel[list[UpdateRemoteUser]]

A list of UpdateRemoteUser entries for bulk remote user modification.

field root: list[UpdateRemoteUser] [Required]

Constraints:

max_length = 1000

When creating or updating remote users you can control activation using lightweight dataclasses passed to the activate parameter:

final class radkit_service.control.async_base_control_api.ActivateForever

Bases: object

Indicator for creating/updating a user that’s activated forever.

model_dump_time() → ExpirationTimestampAndTimeSlice

final class radkit_service.control.async_base_control_api.ActivateMinutes

Bases: object

Indicator for creating/updating a user that’s activated for a certain number of minutes.

minutes: int

model_dump_time() → ExpirationTimestampAndTimeSlice

final class radkit_service.control.async_base_control_api.Deactivate

Bases: object

Indicator for creating/updating a user that’s deactivated.

model_dump_time() → ExpirationTimestampAndTimeSlice

Admins 

Represents the Admin model which includes representation of administrator data used for ControlAPI functions in separate classes depending on the kind of operation.

Warning

There is no password update and no newUsername for Admins using UpdateAdmin through the API .

pydantic model radkit_service.control_api.StoredAdmin

Bases: RADKitBaseModel

Admin model to represent user stored in DB. See NewAdmin datatype for more information.

field username: str [Required]

field email: Literal[''] | EmailStr [Required]

field fullname: str [Required]

field description: str [Required]

field enabled: bool = False

field role_id: int | None = None (alias 'roleId')

field is_sso_only: bool = False (alias 'isSsoOnly')

field external_source_ref: str | None = None (alias 'externalSourceRef')

classmethod from_db_admin( user: DbAdmin, with_role: bool = False, ) → StoredAdmin

pydantic model radkit_service.control_api.NewAdmin

Bases: RADKitBaseModel

Admin model to validate data used for Admin user creation.

field username: str [Required]

Admin username as a string. Example: myadmin

Constraints:

min_length = 1

Validated by:

validate_role_fields
validate_username

field email: Literal[''] | EmailStr [Required]

Admin email as a string.

Validated by:

validate_role_fields

field fullname: str [Required]

Admin full name.

Validated by:

validate_role_fields

field description: str [Required]

String description of admin.

Validated by:

validate_role_fields

field password: CustomSecretStr [Required]

From an external point of view, this is a plain string password for admin login. CustomSecretStr internally wraps this String so passwords are never leaked.

Validated by:

validate_role_fields

field enabled: bool = False

Whether admin should be enabled (False by default).

Validated by:

validate_role_fields

field role: str | None = None

Optional. Role name (str) to assign to this admin.

Validated by:

validate_role_fields

field role_id: int | None = None (alias 'roleId')

Optional. Role ID (int) to assign to this admin.

Validated by:

validate_role_fields

field is_sso_only: bool = False (alias 'isSsoOnly')

Whether the admin can only login via SSO. Defaults to False.

Validated by:

validate_role_fields

pydantic model radkit_service.control_api.NewAdmins

Bases: RADKitRootModel[list[NewAdmin]]

Represents a list of NewAdmin objects. See NewAdmin data type for more information on the fields below.

field root: list[NewAdmin] [Required]

Constraints:

max_length = 1000

pydantic model radkit_service.control_api.UpdateAdmin

Bases: RADKitBaseModel

Admin model to validate data used for updates. Password update is optional.

field username: str [Required]

Stored original username to point at the correct admin, this field is required.

Constraints:

min_length = 1

Validated by:

validate_role_fields

field enabled: UpdateField[bool] = DontUpdate(dontUpdate=True)

Whether admin should be enabled, if empty don’t update.

Validated by:

validate_role_fields

field email: UpdateField[Literal[''] | EmailStr] = DontUpdate(dontUpdate=True)

New email to be updated, if empty don’t update.

Validated by:

validate_role_fields

field fullname: UpdateField[str] = DontUpdate(dontUpdate=True)

New fullname to be updated, if empty don’t update.

Validated by:

validate_role_fields

field description: UpdateField[str] = DontUpdate(dontUpdate=True)

New description to be updated, if empty don’t update.

Validated by:

validate_role_fields

field role: UpdateField[str | None] = DontUpdate(dontUpdate=True)

Optional. Role name (str) to assign to this admin.

Validated by:

validate_role_fields

field role_id: UpdateField[int | None] = DontUpdate(dontUpdate=True) (alias 'roleId')

Optional. Role ID (int) to assign to this admin.

Validated by:

validate_role_fields

field is_sso_only: UpdateField[bool] = DontUpdate(dontUpdate=True) (alias 'isSsoOnly')

Whether the admin can only login via SSO. If empty don’t update.

Validated by:

validate_role_fields

pydantic model radkit_service.control_api.UpdateAdmins

Bases: RADKitRootModel[list[UpdateAdmin]]

Represents a list of UpdateAdmin objects. See UpdateAdmin data type for more information on the fields below.

field root: list[UpdateAdmin] [Required]

Constraints:

max_length = 1000

Devices 

class radkit_service.control_api.DeviceType

Bases: str, Enum

These are the device types used in the Service database as well as the Service and Control APIs. The Service WebUI shows user-friendly versions of these types; those “display types” can be found in the table below as well as in the output of the radkit-control device list-types subcommand.

Note

Changed in 1.6.0: CNBR and CNBROpsHub have been removed (obsolete); display types have been made consistent with official Cisco product names; Control subcommand radkit-control device list-types has been added.

Changed in 1.6.3: enum values have been harmonized (all-uppercase + underscore); database contents will be converted automatically on upgrade; make sure to update your Control scripts and CSV files if you do automated imports.

ACI_OS = 'ACI_OS': Display type: ACI OS (ACI Switch)

AIRE_OS = 'AIRE_OS': Display type: AireOS

APIC = 'APIC': Display type: APIC

ASA = 'ASA': Display type: ASA

BROADWORKS = 'BROADWORKS': Display type: BroadWorks

CATALYST_CENTER = 'CATALYST_CENTER': Display type: Catalyst Center

CCGM = 'CCGM': Display type: CCGM (Catalyst Center Global Manager)

CEDGE = 'CEDGE': Display type: SD-WAN cEdge

CIMC = 'CIMC': Display type: CIMC

CISCO_AP_OS = 'CISCO_AP_OS': Display type: Cisco AP OS

CML = 'CML': Display type: CML

CMS = 'CMS': Display type: CMS

CPS = 'CPS': Display type: CPS (Cisco Policy Suite)

CROSSWORK = 'CROSSWORK': Display type: Crosswork

CSPC = 'CSPC': Display type: CSPC

CUCM = 'CUCM': Display type: CUCM

CVOS = 'CVOS': Display type: CVOS

CVP = 'CVP': Display type: CVP

ESA = 'ESA': Display type: ESA (Secure Email Gateway)

EXPRESSWAY = 'EXPRESSWAY': Display type: Expressway

FDM = 'FDM': Display type: FDM

FMC = 'FMC': Display type: FMC

FTD = 'FTD': Display type: FTD

GENERIC = 'GENERIC': Display type: Generic

HYPERFLEX = 'HYPERFLEX': Display type: HyperFlex

INTERSIGHT = 'INTERSIGHT': Display type: Intersight Appliance WebUI

INTERSIGHT_API = 'INTERSIGHT_API': Display type: Intersight API

IOS_XE = 'IOS_XE': Display type: IOS XE

IOS_XR = 'IOS_XR': Display type: IOS XR

IQ = 'IQ': Display type: IQ

ISE = 'ISE': Display type: ISE

LINUX = 'LINUX': Display type: Linux

NCS_2000 = 'NCS_2000': Display type: NCS-2000

NEXUS_DASHBOARD = 'NEXUS_DASHBOARD': Display type: Nexus Dashboard

NSO = 'NSO': Display type: NSO

NX_OS = 'NX_OS': Display type: NX-OS

RADKIT_SERVICE = 'RADKIT_SERVICE': Display type: RADKit Service

ROUTED_PON = 'ROUTED_PON': Display type: Routed PON

SMA = 'SMA': Display type: SMA (Secure Email and Web Manager)

SNA = 'SNA': Display type: SNA (Secure Network Analytics)

SPLUNK = 'SPLUNK': Display type: Splunk

STAR_OS = 'STAR_OS': Display type: StarOS

UCCE = 'UCCE': Display type: UCCE

UCS_MANAGER = 'UCS_MANAGER': Display type: UCS Manager

ULTRA_CORE_5G_AMF = 'ULTRA_CORE_5G_AMF': Display type: UCC 5G AMF Ops-Center

ULTRA_CORE_5G_PCF = 'ULTRA_CORE_5G_PCF': Display type: UCC 5G PCF Ops-Center

ULTRA_CORE_5G_SMF = 'ULTRA_CORE_5G_SMF': Display type: UCC 5G SMF Ops-Center

WAS = 'WAS': Display type: WAS (Secure Web Appliance)

WLC = 'WLC': Display type: WLC

VMANAGE = 'VMANAGE': Display type: SD-WAN vManage

radkit_service.control_api.StoredDevice: alias of StoredDevice[Annotated[UUID, UuidVersion], int]

radkit_service.control_api.StoredDeviceWithMetadata: alias of StoredDevice[Annotated[UUID, UuidVersion], int]

pydantic model radkit_service.control_api.DeviceSummary

Bases: RADKitBaseModel

Device model to represent data stored in DB. See NewDevice data type for more explanation of the fields below.

field uuid: UUID4 | None = None: Unique identifier of the device to the API.

field name: str | None = None

The device name that appears in RADKit.

Constraints:

min_length = 1

field host: str | None = None

The management IP address or a hostname of the device on the network.

Constraints:

min_length = 1

field device_type: DeviceType | None = None (alias 'deviceType'): Same as the list in the RADKit service UI, identifying the device type in the inventory. Example=’LINUX’.

pydantic model radkit_service.control_api.NewDevice

Bases: RADKitBaseModel

Device model to validate data used for device creation.

field name: CanonicalName [Required]

The device name that will appear in RADKit. Must be unique.

Constraints:

min_length = 1
func = <functools._lru_cache_wrapper object at 0x7f0bbce47110>

Validated by:

validate_provisioning_variant

field host: str [Required]

Takes a management IP address or a hostname of the device on the network.

Constraints:

min_length = 1

Validated by:

validate_hostname
validate_provisioning_variant

field device_type: DeviceType [Required] (alias 'deviceType')

Same as the list in the RADKit service UI, identifying the device type in the inventory. Example=’LINUX’.

Validated by:

validate_provisioning_variant

field jumphost_ref: UUID4 | JumphostName | None = None (alias 'jumphostRef')

Reference to the jumphost device. Default is none.

Validated by:

validate_provisioning_variant

field enabled: bool = False

Boolean (True, False) switch to enable/disable access to device. Default is True.

Validated by:

validate_provisioning_variant

field forwarded_tcp_ports: PortRanges [Optional] (alias 'forwardedTcpPorts')

Identify a range for port forwarding capabilities, example: (‘1024-2047;3456;8000-9999’)

Validated by:

validate_provisioning_variant

field labels: Sequence[int | str] [Optional]

For associating label ids or names.

Validated by:

validate_provisioning_variant

field description: str = ''

String for adding a description to the device. Default is an empty string.

Validated by:

validate_provisioning_variant

field source_key: str | None = None (alias 'sourceKey')

String identifier of device in external device store. Can be UUID. Default is none.

Validated by:

validate_provisioning_variant

field source_dev_uuid: UUID4 | None = None (alias 'sourceDevUuid')

String UUID of device from which device obtained (example: a CatalystCenter uuid as a source of device). Default is none.

Validated by:

validate_provisioning_variant

field meta_data: Annotated[list[MetaDataEntry], reject_duplicate_metadata] [Optional] (alias 'metaData')

A list of one key/value pair of device metadata. Default is none.

Constraints:

max_length = 200
func = <function reject_duplicates.<locals>.validator at 0x7f0bb5a3b380>

Validated by:

validate_provisioning_variant

field terminal: NewTerminal | None = None

Passing a New Terminal object to be associated with the device, documented at NewTerminal data type below

Validated by:

validate_provisioning_variant

field netconf: NewNetconf | None = None

Passing a New Netconf object to be associated with the device, documented at NewNetconf data type below

Validated by:

validate_provisioning_variant

field snmp: NewSNMP | None = None

Passing a New snmp object to be associated with the device, documented at NewSNMP data type below

Validated by:

validate_provisioning_variant

field swagger: NewSwagger | None = None

Passing a New swagger object to be associated with the device, documented at NewSwagger data type below

Validated by:

validate_provisioning_variant

field http: NewHTTP | None = None

Passing a New http object to be associated with the device, documented at NewHttp data type below

Validated by:

_model_validator
validate_provisioning_variant

field device_template_ref: NewDeviceTemplateRef | None = None (alias 'deviceTemplateRef')

Passing a device template ref used for device configuration.

Validated by:

validate_provisioning_variant

pydantic model radkit_service.control_api.UpdateDevice

Bases: BaseUpdateDevice

Device model to validate data used for device updates.

field uuid: UUID4 [Required]

UUID to identify the device. This field is required for an update.

Constraints:

uuid_version = 4

Validated by:

validate_provisioning_variant

pydantic model radkit_service.control_api.StoredTerminal

Bases: RADKitBaseModel

Terminal model used to represent resource stored in DB. See NewTerminal data type for more explanation of the fields below.

field connection_method: ConnectionMethod [Required] (alias 'connectionMethod'): Connection method for terminal connection.

field port: int [Required]: Port for terminal connection.

field username: str [Required]: Username for terminal connection.

field enable_set: bool [Required] (alias 'enableSet'): Whether to send enable command after login on some device types.

field use_insecure_algorithms: bool [Required] (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure SSH algorithms. Default is False.

field jumphost: bool [Required]: Whether this device can be used as a jumphost/tunnel.

field use_tunneling_if_jumphost: bool [Required] (alias 'useTunnelingIfJumphost'): Boolean to use SSH tunneling when using this device as a jumphost (rather than autotyping a second ssh command at the terminal). Default is True.

field provisioning_variant: ProvisioningVariant [Required] (alias 'provisioningVariant'): Provisioning variant to prepare terminal connection.

field capabilities: frozenset[TerminalCapabilities] = frozenset({TerminalCapabilities.DOWNLOAD, TerminalCapabilities.EXEC, TerminalCapabilities.INTERACTIVE, TerminalCapabilities.UPLOAD}): Terminal capabilities.

pydantic model radkit_service.control_api.NewTerminal

Bases: RADKitBaseModel

Terminal model used for resource creation.

field connection_method: Literal[ConnectionMethod.SSH, ConnectionMethod.TELNET, ConnectionMethod.SSHPUBKEY, ConnectionMethod.TELNET_NO_AUTH] = ConnectionMethod.SSH (alias 'connectionMethod'): Takes a string value from the ConnectionMethod enum, for example: “SSH” or “TELNET”. Default is SSH.

field port: int = 22

Integer representing a port of terminal connection. Default is 22.

Validated by:

validate_port_in_range

field username: str = '': String for the username that will be used in terminal connection to the device. Example: “device-username”. Default is an empty string.

field password: AnnotatedCustomSecretStr = CustomSecretStr('')

Plain String for the password that will be used in terminal connection. Default is none.

Constraints:

func = <function <lambda> at 0x7f0bbd684c20>
return_type = <class ‘str’>
when_used = always
json_schema = {‘type’: ‘string’}
mode = serialization

field private_key_password: AnnotatedCustomSecretStr = CustomSecretStr('') (alias 'privateKeyPassword')

Plain string password for decrypting the private key. Default is none.

Constraints:

func = <function <lambda> at 0x7f0bbd684c20>
return_type = <class ‘str’>
when_used = always
json_schema = {‘type’: ‘string’}
mode = serialization

field private_key: AnnotatedCustomSecretStr = CustomSecretStr('') (alias 'privateKey')

String key. Supports keys in OPENSSH format. Default is none.

Constraints:

func = <function <lambda> at 0x7f0bbd684c20>
return_type = <class ‘str’>
when_used = always
json_schema = {‘type’: ‘string’}
mode = serialization

Validated by:

validate_private_key

field enable_set: bool = False (alias 'enableSet'): Boolean. If True, the enable command will be sent after login, along with the enable password, on some device types. Default: False.

field enable: AnnotatedCustomSecretStr = CustomSecretStr('')

Password for entering enable/privileged mode on some device types. Default is none.

Constraints:

func = <function <lambda> at 0x7f0bbd684c20>
return_type = <class ‘str’>
when_used = always
json_schema = {‘type’: ‘string’}
mode = serialization

field use_insecure_algorithms: bool = False (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure SSH algorithms. Default is False.

field jumphost: bool = False: If True, device can act as a jumphost/tunnel. Otherwise, it cannot. Default is False.

field use_tunneling_if_jumphost: bool = True (alias 'useTunnelingIfJumphost'): Boolean to use SSH tunneling when using this device as a jumphost (rather than autotyping a second ssh command at the terminal). Default is True.

field provisioning_variant: ProvisioningVariant = ProvisioningVariant.DEFAULT (alias 'provisioningVariant'): Provisioning variant to prepare terminal connection.

field capabilities: frozenset[TerminalCapabilities] = frozenset({TerminalCapabilities.DOWNLOAD, TerminalCapabilities.EXEC, TerminalCapabilities.INTERACTIVE, TerminalCapabilities.UPLOAD}): Terminal capabilities.

pydantic model radkit_service.control_api.UpdateTerminal

Bases: UpdateModel

Terminal model used for resource update.

Password has to be optional. It allows API users to modify fields without a need to reenter password fields again.

If there are no credentials for the device it’s the API’s consumer responsibility to use the empty string as a value for them.

field connection_method: UpdateField[Literal[ConnectionMethod.SSH, ConnectionMethod.TELNET, ConnectionMethod.SSHPUBKEY, ConnectionMethod.TELNET_NO_AUTH]] = DontUpdate(dontUpdate=True) (alias 'connectionMethod'): Takes a string value from the ConnectionMethod enum, for example: “SSH” or “TELNET”. Default: don’t update.

field port: UpdateField[int] = DontUpdate(dontUpdate=True)

Integer representing a port of terminal connection. Default: don’t update.

Validated by:

validate_port_in_range

field username: UpdateField[str] = DontUpdate(dontUpdate=True): String for the username that will be used in terminal connection to the device. Example: “device-username”. Default: don’t update.

field password: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True): Plain String for the password that will be used in terminal connection. Default: don’t update.

field private_key_password: CustomSecretStr = CustomSecretStr('') (alias 'privateKeyPassword'): Plain string password for decrypting the private key. Default: don’t update.

field private_key: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True) (alias 'privateKey')

String key. Supports keys in OPENSSH format. Default: don’t update.

Validated by:

validate_private_key

field enable_set: UpdateField[bool] = DontUpdate(dontUpdate=True) (alias 'enableSet'): Boolean. If True, the enable command will be sent after login, along with the enable password, on some device types. Default: don’t update.

field enable: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True): Password for entering enable/privileged mode on some device types. Default: don’t update.

field use_insecure_algorithms: UpdateField[bool] = DontUpdate(dontUpdate=True) (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure SSH algorithms. Default: don’t update.

field jumphost: UpdateField[bool] = DontUpdate(dontUpdate=True): If True, device can act as a jumphost/tunnel. Otherwise, it cannot. Default: don’t update.

field use_tunneling_if_jumphost: UpdateField[bool] = DontUpdate(dontUpdate=True) (alias 'useTunnelingIfJumphost'): Boolean to use SSH tunneling when using this device as a jumphost (rather than autotyping a second ssh command at the terminal). Default: don’t update.

field provisioning_variant: UpdateField[ProvisioningVariant] = DontUpdate(dontUpdate=True) (alias 'provisioningVariant'): Provisioning variant to prepare terminal connection.

field capabilities: UpdateField[frozenset[TerminalCapabilities]] = DontUpdate(dontUpdate=True): Terminal capabilities.

pydantic model radkit_service.control_api.StoredNetconf

Bases: RADKitBaseModel

Netconf model used to represent resource stored in DB. See NewNetconf datatype for more information on the fields below.

field port: int [Required]: Port for connection. 830 by default.

field username: str [Required]: Connection credential username.

field use_insecure_algorithms: bool [Required] (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure algorithms. Default is false.

pydantic model radkit_service.control_api.NewNetconf

Bases: RADKitBaseModel

Netconf model used for resource creation.

field port: int = 830

Port for connection. 830 by default.

Validated by:

validate_port_in_range

field username: str = '': Connection credential username.

field password: AnnotatedCustomSecretStr = CustomSecretStr('')

Plain String for connection credential password.

Constraints:

func = <function <lambda> at 0x7f0bbd684c20>
return_type = <class ‘str’>
when_used = always
json_schema = {‘type’: ‘string’}
mode = serialization

field use_insecure_algorithms: bool = False (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure algorithms. Default is false.

pydantic model radkit_service.control_api.UpdateNetconf

Bases: UpdateModel

Netconf model used for resource update.

Passwords have to be optional. It allows API users to modify fields without a need to reenter password fields again.

If there are no credentials for the device it’s the API user’s responsibility to use the empty string as a value for them.

field port: UpdateField[int] = DontUpdate(dontUpdate=True)

Port for connection. Default: don’t update.

Validated by:

validate_port_in_range

field username: UpdateField[str] = DontUpdate(dontUpdate=True): Connection credential username. Default: don’t update.

field password: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True): Plain String for connection credential password. Default: don’t update.

field use_insecure_algorithms: UpdateField[bool] = DontUpdate(dontUpdate=True) (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure algorithms. Default: don’t update.

pydantic model radkit_service.control_api.StoredSNMP

Bases: RADKitBaseModel

SNMP model used to represent resource stored in DB. See NewSNMP datatype for more information.

field version: int [Required]

Integer representing the version of snmp, either 1 or 2. 2 by default.

Constraints:

ge = 1
le = 2

field port: int [Required]: Integer representing the port of snmp. 161 by default.

pydantic model radkit_service.control_api.NewSNMP

Bases: RADKitBaseModel

SNMP model used for resource creation.

field version: int = 2

Integer representing the version of snmp, either 1 or 2. 2 by default.

Constraints:

ge = 1
le = 2

field port: int = 161

Integer representing the port of snmp. 161 by default.

Validated by:

validate_port_in_range

field community_string: AnnotatedCustomSecretStr = CustomSecretStr('') (alias 'communityString')

String SNMP community string. Blank by default.

Constraints:

func = <function <lambda> at 0x7f0bbd684c20>
return_type = <class ‘str’>
when_used = always
json_schema = {‘type’: ‘string’}
mode = serialization

pydantic model radkit_service.control_api.UpdateSNMP

Bases: UpdateModel

SNMP model used for resource update.

field version: UpdateField[SNMPVersion] = DontUpdate(dontUpdate=True): Integer representing the version of snmp, either 1 or 2. Default: don’t update.

field port: UpdateField[int] = DontUpdate(dontUpdate=True)

Integer representing the port of snmp. Default: don’t update.

Validated by:

validate_port_in_range

field community_string: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True) (alias 'communityString'): String SNMP community string. Default: don’t update.

pydantic model radkit_service.control_api.StoredSwagger

Bases: RADKitBaseModel

Swagger model used to represent resource stored in DB. See NewSwagger datatype for more information.

field schema_path: str [Required] (alias 'schemaPath'): Schema for swagger. Default is blank.

field port: int [Required]

field username: str [Required]

field verify: bool | None = None

field use_insecure_algorithms: bool [Required] (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure algorithms. Default is False.

pydantic model radkit_service.control_api.NewSwagger

Bases: RADKitBaseModel

Swagger model used for resource creation.

field schema_path: str = '' (alias 'schemaPath')

Schema for swagger. Default is blank.

Validated by:

validate_schema_path_empty_or_starts_with_slash

field port: int = 443

Integer for specifying specific port. The default is 443.

Validated by:

validate_port_in_range

field username: str = '': Username credential for connecting to swagger. Default is blank.

field password: AnnotatedCustomSecretStr = CustomSecretStr('')

Plain string password credential for connecting to swagger. Default is blank.

Constraints:

func = <function <lambda> at 0x7f0bbd684c20>
return_type = <class ‘str’>
when_used = always
json_schema = {‘type’: ‘string’}
mode = serialization

field verify: bool = True: If True, verify TLS certificate chain. Default is True.

field use_insecure_algorithms: bool = False (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure algorithms. Default is False.

pydantic model radkit_service.control_api.UpdateSwagger

Bases: UpdateModel

Swagger model used for resource update.

Password has to be optional. It allows API users to modify field without a need to reenter password field again.

If there are no credentials for the device it’s the API user’s responsibility to use the empty string as a value for it.

field schema_path: UpdateField[str] = DontUpdate(dontUpdate=True) (alias 'schemaPath'): Schema for swagger. Default: don’t update.

field port: UpdateField[int] = DontUpdate(dontUpdate=True)

Integer for specifying specific port. Default: don’t update.

Validated by:

validate_port_in_range

field username: UpdateField[str] = DontUpdate(dontUpdate=True): Username credential for connecting to swagger. Default: don’t update.

field password: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True): Plain string password credential for connecting to swagger. Default: don’t update.

field verify: UpdateField[bool] = DontUpdate(dontUpdate=True): If True, verify TLS certificate chain. Default: don’t update.

field use_insecure_algorithms: UpdateField[bool] = DontUpdate(dontUpdate=True) (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure algorithms. Default: don’t update.

pydantic model radkit_service.control_api.StoredHTTP

Bases: RADKitBaseModel

HTTP model used to represent resource stored in DB.

field protocol: HTTPProtocol [Required]: Choosing connectivity Protocol the default is HTTPS.

field port: int [Required]: Integer for specifying specific port. The default is 443.

field username: str [Required]: Username credential for connecting to HTTP. Will not be updated if empty.

field verify: bool [Required]: If True, verify TLS certificate chain.

field use_insecure_algorithms: bool [Required] (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure algorithms. Default is False.

field authentication_extra: str | None = None (alias 'authenticationExtra'): Optional type of authentication. Default depends on the device type. E.g. for ISE it is “Internal”.

pydantic model radkit_service.control_api.NewHTTP

Bases: RADKitBaseModel

HTTP model used for resource creation.

field protocol: HTTPProtocol = HTTPProtocol.HTTPS: Choosing connectivity Protocol. The default is HTTPS.

field port: int = 443

Integer for specifying specific port. The default is 443.

Validated by:

validate_port_in_range

field username: str = '': Username credential for connecting to HTTP. Blank by default.

field password: AnnotatedCustomSecretStr = CustomSecretStr('')

Plain string password credential for connecting to HTTP. Blank by default.

Constraints:

func = <function <lambda> at 0x7f0bbd684c20>
return_type = <class ‘str’>
when_used = always
json_schema = {‘type’: ‘string’}
mode = serialization

field verify: bool = True: If True, verify TLS certificate chain. True by default.

field use_insecure_algorithms: bool = False (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure algorithms. Default is False.

field authentication_extra: str | None = None (alias 'authenticationExtra'): Optional type of authentication. Default depends on the device type. E.g. for ISE it is Internal.

field private_key: AnnotatedCustomSecretStr = CustomSecretStr('') (alias 'privateKey')

String key for client certificate authentication. Supports keys in PEM format. Default is none.

Constraints:

func = <function <lambda> at 0x7f0bbd684c20>
return_type = <class ‘str’>
when_used = always
json_schema = {‘type’: ‘string’}
mode = serialization

Validated by:

validate_private_key

field private_key_password: AnnotatedCustomSecretStr = CustomSecretStr('') (alias 'privateKeyPassword')

Plain string password for decrypting the private key. Default is none.

Constraints:

func = <function <lambda> at 0x7f0bbd684c20>
return_type = <class ‘str’>
when_used = always
json_schema = {‘type’: ‘string’}
mode = serialization

pydantic model radkit_service.control_api.UpdateHTTP

Bases: UpdateModel

HTTP model used for resource update.

field protocol: UpdateField[HTTPProtocol] = DontUpdate(dontUpdate=True): Choosing connectivity Protocol. Default: don’t update.

field port: UpdateField[int] = DontUpdate(dontUpdate=True)

Integer for specifying specific port. Default: don’t update.

Validated by:

validate_port_in_range

field username: UpdateField[str] = DontUpdate(dontUpdate=True): Username credential for connecting to HTTP. Default: don’t update.

field password: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True): Plain String password credential for connecting to HTTP. Default: don’t update.

field verify: UpdateField[bool] = DontUpdate(dontUpdate=True): If True, verify TLS certificate chain. Default: don’t update.

field use_insecure_algorithms: UpdateField[bool] = DontUpdate(dontUpdate=True) (alias 'useInsecureAlgorithms'): Boolean for allowing usage of obsolete/insecure algorithms. Default: don’t update.

field authentication_extra: UpdateField[str | None] = DontUpdate(dontUpdate=True) (alias 'authenticationExtra'): Optional type of authentication. Default: don’t update.

field private_key_password: CustomSecretStr = CustomSecretStr('') (alias 'privateKeyPassword'): Plain string password for decrypting the private key. Default: don’t update.

field private_key: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True) (alias 'privateKey')

Plain string password for decrypting the private key. default is none. Default: don’t update.

Validated by:

validate_private_key

pydantic model radkit_service.control_api.UpdateMetaDataSet

Bases: RADKitBaseModel

Data model for metadata to be added, removed or replaced on an entry in the DB.

field replace: Annotated[list[MetaDataEntry] | None, reject_duplicate_metadata] = None

Optional. A list of metadata entries to set. These will replace all metadata currently in place. May not be used together with add or remove.

Constraints:

max_length = 200
func = <function reject_duplicates.<locals>.validator at 0x7f0bb5a3b380>

Validated by:

check_add_remove_are_distinct
check_metadata_replace_xor_add_remove

field add: Annotated[list[MetaDataEntry], reject_duplicate_metadata] [Optional]

Optional. A list of metadata entries to be added to those currently in place, or changed. May be used together with remove.

Constraints:

max_length = 200
func = <function reject_duplicates.<locals>.validator at 0x7f0bb5a3b380>

Validated by:

check_add_remove_are_distinct
check_metadata_replace_xor_add_remove

field remove: list[str] [Optional]

Optional. A list of metadata keys to be removed from those currently in place. May be used together with add.

Validated by:

check_add_remove_are_distinct
check_metadata_replace_xor_add_remove

pydantic settings radkit_service.control_api.CatalystCenterImportSettings

Bases: BaseImportSettings

Data model for available import settings for Catalyst Center device type.

field import_terminal_credentials: bool = True (alias 'importTerminalCredentials'): Whether to import terminal credentials (defaults to True)

field import_http_credentials: bool = True (alias 'importHttpCredentials'): Whether to import HTTP credentials (defaults to True)

field import_snmp_credentials: bool = True (alias 'importSnmpCredentials'): Whether to import SNMP credentials (defaults to True)

field tag: str | None = None: Optional tag to filer the device inventory on

field import_nodes: bool = True (alias 'importCatalystCenterNodes'): Whether other nodes should be imported (defaults to True)

field import_cimc: bool = True (alias 'importCatalystCenterCimc'): Whether to import CIMC node(-s) (defaults to True)

field import_dr: bool = True (alias 'importCatalystCenterDr'): Whether to import Disaster Recovery node(-s) (defaults to True)

field nodes_source_address_type: IpSourceType = IpSourceType.MANAGEMENT (alias 'nodesSourceAddressType'): The type of the source address to choose when importing other nodes (defaults to ‘Management’)

pydantic settings radkit_service.control_api.CiscoAPICImportSettings

Bases: BaseImportSettings

Data model for available import settings for APIC device type.

field ip_source: IpSource | None = IpSource.OUT_OF_BAND (alias 'ipSource'): Source of the IP address: IN_BAND or OUT_OF_BAND (defaults to OUT_OF_BAND)

pydantic settings radkit_service.control_api.CSPCImportSettings: Bases: BaseImportSettings

pydantic settings radkit_service.control_api.CUCMImportSettings: Bases: BaseImportSettings

pydantic settings radkit_service.control_api.FMCImportSettings: Bases: BaseImportSettings

pydantic settings radkit_service.control_api.VManageImportSettings: Bases: BaseImportSettings

pydantic settings radkit_service.control_api.WLCImportSettings: Bases: BaseImportSettings

Roles 

Represents the Role model which includes representation of role data used for ControlAPI functions. Roles define sets of permissions (claims) that can be assigned to administrators.

class radkit_service.control_api.Claim

Bases: str, Enum

Enum representing all possible claims in the system.

Note:: Each change in this model requires a database migration.

READ_DEVICES = 'READ_DEVICES'

MODIFY_DEVICES = 'MODIFY_DEVICES'

READ_REMOTE_USERS = 'READ_REMOTE_USERS'

MODIFY_REMOTE_USERS = 'MODIFY_REMOTE_USERS'

READ_ADMINS = 'READ_ADMINS'

MODIFY_ADMINS = 'MODIFY_ADMINS'

READ_ROLES = 'READ_ROLES'

MODIFY_LABELS = 'MODIFY_LABELS'

READ_LOGS = 'READ_LOGS'

READ_ACTIVITY = 'READ_ACTIVITY'

MODIFY_ACTIVITY = 'MODIFY_ACTIVITY'

READ_EXTERNAL_SOURCES = 'READ_EXTERNAL_SOURCES'

READ_SETTINGS = 'READ_SETTINGS'

MODIFY_SETTINGS = 'MODIFY_SETTINGS'

READ_DEVICE_TEMPLATES = 'READ_DEVICE_TEMPLATES'

CONNECT_DIRECT_RPC = 'CONNECT_DIRECT_RPC'

pydantic model radkit_service.control_api.StoredRole

Bases: RADKitBaseModel

Role model to represent role data stored in DB in API.

field id: int [Required]: Unique role ID

field name: str [Required]: Unique role name

field description: str = '': Role description

field claims: frozenset[Claim] [Optional]: Set of claims assigned to this role

field read_only: bool = False (alias 'readOnly'): Whether this role is read-only and cannot be modified or deleted

field is_sysadmin: bool = False (alias 'isSysadmin'): Whether this role is a system administrator role

classmethod from_db_role( db_role: DbRole, ) → StoredRole

pydantic model radkit_service.control_api.NewRole

Bases: RADKitBaseModel

Role model for creating new roles.

field name: RoleName [Required]

Unique role name

Constraints:

min_length = 1
max_length = 100
func = <functools._lru_cache_wrapper object at 0x7f0bbce47110>

Validated by:

_validate_sysadmin_claims_mutual_exclusion

field description: RoleDescription = ''

Role description

Constraints:

max_length = 500

Validated by:

_validate_sysadmin_claims_mutual_exclusion

field claims: frozenset[Claim] [Optional]

Set of claims assigned to this role

Validated by:

_validate_sysadmin_claims_mutual_exclusion

field is_sysadmin: bool = False (alias 'isSysadmin')

Whether this role is a system administrator role

Validated by:

_validate_sysadmin_claims_mutual_exclusion

pydantic model radkit_service.control_api.UpdateRole

Bases: RADKitBaseModel

Role model to validate data used for updates

field id: int [Required]

A unique id for API calls to point to right role to be updated.

Validated by:

_auto_clear_claims_for_sysadmin

field name: UpdateField[RoleName] = DontUpdate(dontUpdate=True)

Role name. If DONT_UPDATE, don’t modify.

Validated by:

_auto_clear_claims_for_sysadmin
_validate_name

field description: UpdateField[RoleDescription] = DontUpdate(dontUpdate=True)

Role description. If DONT_UPDATE, don’t modify.

Validated by:

_auto_clear_claims_for_sysadmin

field claim_update: UpdateClaimSet [Optional] (alias 'claimUpdate')

Claims to be added/removed/replaced on the role.

Validated by:

_auto_clear_claims_for_sysadmin

field is_sysadmin: UpdateField[bool] = DontUpdate(dontUpdate=True) (alias 'isSysadmin')

Whether this role is a system administrator role. If DONT_UPDATE, don’t modify.

Validated by:

_auto_clear_claims_for_sysadmin

Labels 

pydantic model radkit_service.control_api.NewLabel

Bases: RADKitBaseModel

Label model to validate data used for creation.

field name: str [Required]

A string representing a label name. example=”SR12345”.

Constraints:

min_length = 1
max_length = 40

Validated by:

_validate_name_whitespace

field color: str = '#000000'

A string representing a color in HEX Code, example “#ff0000”.

Validated by:

_validate_css_color

field is_context: bool = False (alias 'isContext'): Whether this label can be used as context label for service-side filtering.

pydantic model radkit_service.control_api.UpdateLabel

Bases: RADKitBaseModel

Label model to validate data used for updates

field id: int [Required]: A unique id for API calls to point to right label to be updated.

field name: UpdateField[NonEmptyLabel] = DontUpdate(dontUpdate=True)

A string representing a label name. example=”SR12345”, if empty don’t modify.

Validated by:

_validate_name_whitespace

field color: UpdateField[str] = DontUpdate(dontUpdate=True)

A string representing a color in HEX Code, example “#ff0000”. If empty don’t modify.

Validated by:

_validate_css_color

pydantic model radkit_service.control_api.StoredLabel

Bases: RADKitBaseModel

Label model to represent remote user data stored in DB in API. See NewLabel data type for more explanation of the fields below:

field id: int [Required]

field name: str [Required]

field color: str [Required]

field is_context: bool = False (alias 'isContext')

classmethod from_db_label( label: DbLabel, ) → StoredLabel

pydantic model radkit_service.control_api.UpdateLabelSet

Bases: RADKitBaseModel

Data model for labels to be added, removed or replaced on an entry in the DB.

field replace: Sequence[int | str] | None = None

Optional. A sequence of integers or strings representing the labels to be affixed. These will replace any labels currently in place. May not be used together with add or remove.

Validated by:

check_labels_replace_xor_add_remove

field add: Sequence[int | str] [Optional]

Optional. A sequence of integers or strings representing the labels to be added to those currently in place. May be used together with remove.

Validated by:

check_labels_replace_xor_add_remove

field remove: Sequence[int | str] [Optional]

Optional. A sequence of integers or strings representing the labels to be removed from those currently in place. May be used together with add.

Validated by:

check_labels_replace_xor_add_remove

is_empty() → bool: Check if the label set is empty, i.e. no labels to add, remove or replace.

Settings 

pydantic model radkit_service.control_api.SettingChange

Bases: RADKitBaseModel

Requested settings changes to perform. If remove is set to True then value is ignored.

field setting: str [Required]

field layers: list[Literal['toml', 'api']] [Required]

Constraints:

min_length = 1
max_length = 2

field value: Any = None

field remove: bool = False

pydantic model radkit_service.control_api.APISettingInfo

Bases: RADKitBaseModel

Setting detailed information.

field setting: str [Required]: Setting name

field effective_value: Annotated[Any, PlainSerializer(serialize_effective_value_helper, return_type=Any, when_used='json')] = None (alias 'effectiveValue')

Effective value of the setting

Constraints:

func = <function serialize_effective_value_helper at 0x7f0bb4974360>
return_type = typing.Any
when_used = json

field type: str [Required]: Type of the setting.

field value_source: Literal['default', 'toml', 'env', 'cli', 'api'] [Required] (alias 'valueSource'): Shows from which layer setting value was taken

field description: str [Required]: Short description of the setting.

field api_writable: bool [Required] (alias 'apiWritable'): Boolean, if false, setting cannot be set via the api.

field api_persistent: bool [Required] (alias 'apiPersistent'): Boolean if false, setting cannot be saved to disk via the api.

field webui_visible: bool [Required] (alias 'webuiVisible'): Boolean, if true, the settings web interface will show this setting.

field requires_webserver_restart: bool [Required] (alias 'requiresWebserverRestart'): Boolean, if true, changing this setting requires a webserver restart.

field layer_values: dict[Pedigree, Annotated[Any, PlainSerializer(serialize_effective_value_helper, return_type=Any, when_used='json')]] [Required] (alias 'layerValues'): Shows how the setting was set

field layer_errors: dict[Pedigree, str] [Required] (alias 'layerErrors'): Shows the errors from layers

classmethod from_resolve_result( resolve_result: ResolveResult[Any], ) → APISettingInfo