ISE API Reference

Overview

Cisco ISE exposes five distinct APIs for automation, monitoring, and integration. This reference provides complete coverage with both netapi CLI and curl examples for every operation.

ISE API Landscape

API Comparison Matrix

API Port Auth Protocol Endpoints Primary Use

ERS

9060

Basic

REST/JSON

199

Configuration CRUD (endpoints, groups, policies)

OpenAPI v1

443

Basic

REST/JSON

100

Policy management, conditions, dictionaries

MnT

443

Basic

REST/XML

~20

Session monitoring, CoA, auth logs

DataConnect

2484

JDBC

Oracle SQL

376+ views

Analytics, reporting, historical data

pxGrid 2.0

8910

mTLS

WebSocket

Pub/Sub

Real-time events, context sharing

Quick Start

# Load credentials
dsource d000 dev/network

# Test ERS connectivity
netapi ise get-endpoints --limit 1

# Test OpenAPI connectivity
netapi ise get-policy-sets

# Test MnT connectivity
netapi ise mnt sessions

# Test DataConnect connectivity
netapi ise dc test

Authentication Methods

Basic Authentication (ERS, OpenAPI, MnT)

Authentication Required

ISE ERS and OpenAPI use HTTP Basic Authentication. Credentials must have ERS Admin role enabled in ISE Administration > System > Admin Access > Administrators.

# Load credentials from secrets manager
dsource d000 dev/network

# Credentials available as environment variables:
#   ISE_API_USER - Username with ERS Admin role
#   ISE_API_PASS - Password

mTLS Certificate (pxGrid)

Certificate Authentication Required

pxGrid 2.0 uses mutual TLS (mTLS) for authentication. You need:

  1. Client certificate issued by ISE Internal CA or trusted external CA

  2. Client private key (keep secure)

  3. ISE trust chain (ISE Admin CA + Root CA)

# Certificate paths
PXGRID_CERT="/etc/ssl/certs/pxgrid-client.pem"
PXGRID_KEY="/etc/ssl/private/pxgrid-client.key"
PXGRID_CA="/etc/ssl/certs/ise-trust-chain.pem"

# Verify certificate
openssl x509 -in "$PXGRID_CERT" -subject -issuer -dates -noout

See pxGrid PKI Setup for certificate issuance.

JDBC (DataConnect)

# DataConnect uses Oracle JDBC authentication
# Credentials configured in ISE: Administration > System > Settings > DataConnect

# Test connection
netapi ise dc test

# Or with JDBC directly
java -jar ojdbc11.jar \
  jdbc:oracle:thin:@//${ISE_HOST}:2484/cpm10 \
  "${ISE_DC_USER}" "${ISE_DC_PASS}"

Response Structures

Each API uses a different response format:

ERS Response

ERS Response Structure

All ERS API responses follow a consistent structure:

List Operations (GET collection)

{
  "SearchResult": {
    "total": 142,
    "resources": [
      {
        "id": "uuid-string",
        "name": "resource-name",
        "description": "optional description",
        "link": {
          "rel": "self",
          "href": "https://ise:9060/ers/config/resource/uuid",
          "type": "application/json"
        }
      }
    ]
  }
}

Single Resource (GET by ID/name)

{
  "ERSResourceName": {
    "id": "uuid-string",
    "name": "resource-name",
    "description": "optional description",
    // Resource-specific fields
    "link": {
      "rel": "self",
      "href": "https://ise:9060/ers/config/resource/uuid"
    }
  }
}

Create/Update Success (POST/PUT)

{
  "UpdatedFieldsList": {
    "updatedField": [
      {
        "field": "fieldName",
        "oldValue": "old",
        "newValue": "new"
      }
    ]
  }
}

Error Response

{
  "ERSResponse": {
    "operation": "POST-create",
    "messages": [
      {
        "title": "Error description",
        "type": "ERROR",
        "code": "Application error code"
      }
    ]
  }
}

jq Extraction Patterns

# List all resources
jq '.SearchResult.resources[]'

# Get names only
jq -r '.SearchResult.resources[].name'

# Get ID and name pairs
jq '.SearchResult.resources[] | {id, name}'

# Single resource fields
jq '.ERSEndPoint | {mac: .mac, group: .groupId}'

OpenAPI Response

OpenAPI Response Structure

ISE OpenAPI v1 responses use a different structure than ERS:

List Operations (GET collection)

{
  "response": [
    {
      "id": "uuid-string",
      "name": "resource-name",
      "rank": 1,
      "state": "enabled",
      // Resource-specific fields
      "link": {
        "rel": "self",
        "href": "/api/v1/policy/network-access/policy-set/uuid"
      }
    }
  ],
  "version": "1.0.0"
}

Single Resource (GET by ID)

{
  "response": {
    "id": "uuid-string",
    "name": "resource-name",
    // All resource fields
  },
  "version": "1.0.0"
}

Create/Update Success (POST/PUT)

{
  "response": {
    "id": "newly-created-uuid",
    "name": "resource-name",
    // Created/updated resource
  },
  "version": "1.0.0"
}

Error Response

{
  "response": {
    "code": 400,
    "message": "Error description"
  },
  "version": "1.0.0"
}

jq Extraction Patterns

# List all resources
jq '.response[]'

# Get names only
jq -r '.response[].name'

# Get enabled items
jq '.response[] | select(.state == "enabled")'

# Policy set with hit counts
jq '.response[] | {name, rank, hits: .hitCounts, state}'

HTTP Status Codes

HTTP Status Codes

Code Meaning Action

2xx Success

200

OK - Request successful

Parse response body

201

Created - Resource created

Check Location header for new resource URL

204

No Content - Delete successful

No body returned

4xx Client Errors

400

Bad Request - Invalid syntax

Check JSON format, required fields

401

Unauthorized - Auth failed

Verify credentials, check ERS Admin role

403

Forbidden - No permission

User lacks required RBAC permissions

404

Not Found - Resource missing

Verify ID/name, check resource exists

405

Method Not Allowed

Check HTTP method (GET/POST/PUT/DELETE)

409

Conflict - Already exists

Use PUT to update, or DELETE first

415

Unsupported Media Type

Add Content-Type: application/json header

422

Unprocessable Entity

Valid JSON but semantic error (e.g., invalid MAC format)

429

Too Many Requests

Rate limited - wait and retry

5xx Server Errors

500

Internal Server Error

Check ISE logs, retry later

502

Bad Gateway

ISE service issue, check node health

503

Service Unavailable

ISE overloaded or in maintenance

504

Gateway Timeout

Request too slow, increase timeout or paginate

netapi vs curl

Every operation in this reference shows both approaches:

Approach When to Use

netapi CLI

Day-to-day operations, scripting, CI/CD pipelines. Handles auth, pagination, error formatting.

curl

Learning APIs, debugging, custom integrations, when netapi doesn’t support an operation.

Example: List Endpoints

netapi (simple)
netapi ise get-endpoints
curl (explicit)
dsource d000 dev/network
curl -sk -u "${ISE_API_USER}:${ISE_API_PASS}" \
  "https://${ISE_PAN_IP}:9060/ers/config/endpoint" \
  -H "Accept: application/json" | jq '.SearchResult.resources[] | {name, id}'

API Coverage by Category

Identity Management

Resource ERS OpenAPI netapi

Endpoints

Endpoint Groups

Identity Groups

Internal Users

Planned

Network Access Policy

Resource ERS OpenAPI netapi

Policy Sets

Authentication Rules

Authorization Rules

Authorization Profiles

dACLs

TrustSec

Resource ERS OpenAPI netapi

SGTs

SGACLs

Planned

IP-SGT Mappings

Planned

Egress Matrix

Planned

Monitoring & Operations

Resource MnT DataConnect netapi

Active Sessions

Session Details

CoA (Disconnect/Reauth)

Auth History

Failure Reasons

Detailed References

See Also