Install & Compatibility
Where this runs
tested against v2.4.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.900s · 90.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.6s · import 1.608s · 91MB
92MB installed
● package 92MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
IdentityServicesEngineAPI
✓ from ciscoisesdk import IdentityServicesEngineAPI
✗ from ciscoisesdk.api import IdentityServicesEngineAPI
The primary API class is directly exposed under the top-level package, not within a sub-module like `api`.
ApiError
✓ from ciscoisesdk.exceptions import ApiError
Common exceptions are found in the `exceptions` submodule for proper error handling.
This quickstart demonstrates how to initialize the `IdentityServicesEngineAPI` client using environment variables for credentials and then make a basic API call to retrieve all configured network devices. It includes error handling for API-specific and general exceptions. Remember to replace placeholder values or set environment variables.
import os
from ciscoisesdk import IdentityServicesEngineAPI, ApiError
# Set these environment variables for authentication
# IDENTITY_SERVICES_ENGINE_USERNAME
# IDENTITY_SERVICES_ENGINE_PASSWORD
# IDENTITY_SERVICES_ENGINE_BASE_URL
# IDENTITY_SERVICES_ENGINE_VERSION (e.g., '3.3_patch_1' or '3.5.0')
username = os.environ.get('IDENTITY_SERVICES_ENGINE_USERNAME', 'YOUR_ISE_USERNAME')
password = os.environ.get('IDENTITY_SERVICES_ENGINE_PASSWORD', 'YOUR_ISE_PASSWORD')
base_url = os.environ.get('IDENTITY_SERVICES_ENGINE_BASE_URL', 'https://your-ise-server.example.com')
version = os.environ.get('IDENTITY_SERVICES_ENGINE_VERSION', '3.3_patch_1')
try:
# Create a connection object
api = IdentityServicesEngineAPI(
username=username,
password=password,
base_url=base_url,
version=version,
uses_api_gateway=True, # Often True for modern ISE deployments
verify=False # Set to True in production with proper CA-signed certs
)
# Example: Get all network devices
print(f"Attempting to retrieve network devices from {base_url} (ISE version: {version})...")
network_devices_response = api.network_device.get_all()
if network_devices_response and network_devices_response.response:
print("Successfully retrieved network devices:")
for device in network_devices_response.response:
print(f" ID: {device.get('id')}, Name: {device.get('name')}")
else:
print("No network devices found or unexpected response.")
except ApiError as e:
print(f"API Error: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingIn `v2.2.1`, the `NetworkDeviceGroup` API parameter name changed from 'ndgtype' to a more descriptive 'other...', which can break existing scripts interacting with this specific API.fixReview and update parameter names for `NetworkDeviceGroup` API calls according to the latest documentation or the `CHANGELOG.md`.
affects: >=2.2.1
gotchaThe `IdentityServicesEngineAPI` constructor requires valid authentication credentials (username/password or encoded_auth, or client_cert/client_key) and a base URL. Failure to provide these, either directly or via environment variables, will result in an `AccessTokenError` or `TypeError`.fixEnsure `IDENTITY_SERVICES_ENGINE_USERNAME`, `IDENTITY_SERVICES_ENGINE_PASSWORD`, `IDENTITY_SERVICES_ENGINE_BASE_URL` (and optionally `IDENTITY_SERVICES_ENGINE_VERSION`) environment variables are set, or pass them as arguments to the `IdentityServicesEngineAPI` constructor.
affects: All versions
gotchaUsing an unsupported or unknown ISE API `version` (e.g., '0.1.12') when initializing `IdentityServicesEngineAPI` will raise a `VersionError`. The SDK only supports specific ISE API versions (e.g., 3.1.0, 3.1.1, 3.1_Patch_1, 3.2_beta, 3.3_patch_1, 3.5.0) which are listed in the compatibility matrix.fixConsult the SDK's compatibility matrix (e.g., in the GitHub README or Read the Docs) and specify a supported `version` string (e.g., `version='3.3_patch_1'`).
affects: All versions
deprecatedCisco ISE API version 3.1.1 is considered the same as 3.1_Patch_1, and future releases of ISE are expected to remove direct support for 3.1.1.fixMigrate API calls to target ISE API version `3.1_Patch_1` or a newer supported version (e.g., `3.3_patch_1`, `3.5.0`) to ensure future compatibility.
affects: ISE API versions 3.1.1, affecting ciscoisesdk users targeting this version
gotchaThe library explicitly requires Python versions `>=3.12` and `<4.0`. Attempting to install or run with unsupported Python versions will lead to installation failures or runtime issues.fixEnsure your Python environment is running a version within the specified range: Python 3.12 or higher, but strictly less than Python 4.0.
affects: All versions
gotchaVersion 2.4.2 introduced certificate-based authentication (mTLS) for all API calls, including new `client_cert` and `client_key` parameters. This is a secure alternative to username/password but requires ISE 3.3+ and proper certificate setup.fixFor enhanced security, upgrade to `ciscoisesdk` v2.4.2 or later and configure certificate-based authentication as described in the documentation, ensuring your ISE deployment is version 3.3 or higher. Otherwise, continue with username/password authentication.
affects: <2.4.2 (feature not present)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'imp'
This error occurs when using Python versions 3.12 or newer, because the 'imp' module, which was used internally by some dependencies of ciscoisesdk, has been deprecated and removed from the Python standard library.
fixUpgrade the `ciscoisesdk` library to its latest version (which should address Python 3.12+ compatibility) using `pip install --upgrade ciscoisesdk`. If the issue persists, consider using an earlier Python version (e.g., Python 3.11) until a compatible version of the SDK or its dependencies is released.
VersionError: Unknown API version, known versions are 3.1.0, 3.1.1, 3.1_Patch_1 and 3.2_beta.
This error indicates that the API version specified when initializing the `IdentityServicesEngineAPI` object is not supported by the `ciscoisesdk` library or the connected Cisco ISE instance. The exact list of known versions will vary depending on the SDK version and ISE version.
fixProvide a valid and supported API version when creating the `IdentityServicesEngineAPI` object. Refer to the Cisco ISE documentation or the `ciscoisesdk` documentation for the list of compatible API versions. For example: `api = IdentityServicesEngineAPI(..., version='3.2_beta')`.
AccessTokenError
This error is raised when the `IdentityServicesEngineAPI` object is initialized without sufficient authentication credentials (username and password, or an encoded authentication token), or if the corresponding environment variables (IDENTITY_SERVICES_ENGINE_USERNAME, IDENTITY_SERVICES_ENGINE_PASSWORD, IDENTITY_SERVICES_ENGINE_ENCODED_AUTH) are not set.
fixEnsure that you provide valid `username` and `password` arguments, or a `encoded_auth` string, directly to the `IdentityServicesEngineAPI` constructor, or set the appropriate environment variables before initializing the API object. Example: `api = IdentityServicesEngineAPI(username='admin', password='Cisco123!', base_url='https://ise.example.com')`.
Connection refused
This is a low-level network error indicating that the client attempted to connect to a server (Cisco ISE) on a specific IP address and port, but the server actively refused the connection. This can be due to the ISE instance not running, the API services not being enabled, a firewall blocking the connection, or an incorrect `base_url` or port specified.
fixVerify that the Cisco ISE instance is running, that the relevant API services (ERS, OpenAPI, etc.) are enabled and accessible, and that no firewalls are blocking communication on the specified `base_url` and port (typically 443 for API Gateway, or 9060 for ERS APIs). Double-check the `base_url` provided to `IdentityServicesEngineAPI`.
Upgrade
Version history
2.4.4latest on PyPI · released May 8, 2026
Audit
Dependencies
pythonrequiredRequired Python version range for the SDK.