Cisco Identity Services Engine Platform SDK

2.4.3 · active · verified Wed Apr 15

The `ciscoisesdk` is a community-developed Python SDK for interacting with Cisco Identity Services Engine (ISE) APIs. It provides a Pythonic wrapper around the RESTful ISE APIs, simplifying tasks like network device management, user authentication, and policy configuration. The library is currently at version 2.4.3 and sees frequent minor and patch releases, indicating active development.

Warnings

breaking In `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.
Fix: Review and update parameter names for `NetworkDeviceGroup` API calls according to the latest documentation or the `CHANGELOG.md`.
gotcha The `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`.
Fix: Ensure `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.
gotcha Using 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.
Fix: Consult 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'`).
deprecated Cisco 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.
Fix: Migrate 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.
gotcha The 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.
Fix: Ensure your Python environment is running a version within the specified range: Python 3.12 or higher, but strictly less than Python 4.0.
gotcha Version 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.
Fix: For 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.

Install

pip install ciscoisesdk Install latest version

Imports

IdentityServicesEngineAPI
wrong:
```
from ciscoisesdk.api import IdentityServicesEngineAPI
```
correct:
```
from ciscoisesdk 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.

Quickstart

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}")

view raw JSON →