ISE ERS API Complete Command Reference

Complete command reference for managing Cisco ISE via the External RESTful Services (ERS) API using netapi.

Overview

The ERS API (Port 9060) provides configuration management for ISE. All commands require authentication via dsec.

# Load credentials from dsec
DSEC_SECURITY_MODE=permissive eval $(dsec source d000 dev/network)

# Or set manually
export ISE_PAN_IP="10.50.1.21"
export ISE_API_USER="ers_admin"
export ISE_API_PASS="your_password"

Endpoint Management

Get Endpoint

Retrieve detailed information about a specific endpoint by MAC address.

netapi ise get-endpoint <MAC_ADDRESS>

Example:

netapi ise get-endpoint b4:e9:b8:f6:c8:17

Output:

{
  "id": "uuid-here",
  "name": "b4:e9:b8:f6:c8:17",
  "mac": "B4:E9:B8:F6:C8:17",
  "groupId": "endpoint-identity-group-id",
  "staticGroupAssignment": true,
  "description": "Dr. Shahab workstation"
}

Create Endpoint

Pre-register an endpoint with optional group assignment.

netapi ise create-endpoint <MAC_ADDRESS> \
  --group <GROUP_NAME> \
  --description "<DESCRIPTION>"

Example:

netapi ise create-endpoint b4:e9:b8:f6:c8:17 \
  --group "Linux-Research-Onboarding" \
  --description "chlxsbg.la.ad.chla.org - SRT Building 9th Floor"

Use Cases: - Pre-register devices before deployment - Assign to onboarding groups for MAB authentication - Track device ownership and location

Update Endpoint

Modify existing endpoint attributes including group membership, description, and static assignment flags.

netapi ise update-endpoint <MAC_ADDRESS> \
  --group <NEW_GROUP_NAME> \
  --description "<NEW_DESCRIPTION>" \
  --static-group \
  --static-profile

Options: - --group - Set endpoint identity group - --description - Update endpoint description - --static-group - Enable static group assignment (prevents profiling override) - --static-profile - Enable static profile assignment - --no-static-group - Disable static group assignment - --no-static-profile - Disable static profile assignment

Example (Migration Scenario):

# Move from onboarding to production with static assignment
netapi ise update-endpoint b4:e9:b8:f6:c8:17 \
  --group "Linux-Research-Production" \
  --description "Migrated to EAP-TLS - 2026-01-28" \
  --static-group

Known Limitation (ciscoisesdk): Due to a bug in the underlying ciscoisesdk library, the --static-group flag may not properly set staticGroupAssignment=true in ISE. This causes ISE Profiling to override manual group assignments.

Workaround: Use ISE GUI to set endpoint group with "Static Assignment" checkbox enabled.

See: .principia/docs/ise-endpoint-group-profiling-issue.adoc for technical details.

Update Endpoint Group

Convenience command to quickly change an endpoint’s identity group assignment.

netapi ise update-endpoint-group <MAC_ADDRESS> <GROUP_NAME> [--static/--no-static]

Options: - --static - Enable static group assignment (default: true) - --no-static - Allow ISE profiling to change group

Example:

# Move endpoint to Linux-Research-Onboarding group with static assignment
netapi ise update-endpoint-group b4:e9:b8:f6:c8:17 "Linux-Research-Onboarding" --static

# Quick group change (static by default)
netapi ise update-endpoint-group 00:11:22:33:44:55 "Blacklist"

Critical ISE Profiling Behavior:

Without static assignment enabled, ISE Profiling service will automatically override manual group assignments. Endpoints will be moved to system groups like "Unknown" or "Profiled" during profiling runs.

To ensure group assignment persists: 1. Always use --static flag (it’s the default) 2. Verify after update: staticGroupAssignment must be true 3. If update fails, use ISE GUI as workaround

Verification:

# Check if static assignment is enabled
netapi ise get-endpoint b4:e9:b8:f6:c8:17

# Output should show:
#   Identity Group: Linux-Research-Onboarding
#   Static Assignment: true  ← MUST BE TRUE

Known Limitation (ciscoisesdk): This command may fail to properly set staticGroupAssignment=true due to ciscoisesdk bug. ISE API returns empty UpdatedFieldsList, indicating the update was rejected.

Symptoms: - Command reports success but groupId doesn’t change - Endpoint remains in "Unknown" or "Profiled" system groups - staticGroupAssignment stays false

Workaround: Use ISE GUI: 1. Navigate to Context Visibility → Endpoints 2. Search for MAC address 3. Edit endpoint 4. Set identity group and CHECK "Static Assignment" checkbox 5. Save

Technical Details: See .principia/docs/ise-endpoint-group-profiling-issue.adoc

Delete Endpoint

Remove endpoint registration from ISE.

netapi ise delete-endpoint <MAC_ADDRESS>

Deleting an endpoint removes it from ISE’s endpoint database. The device will be treated as unknown on next authentication attempt.

List Endpoints

Retrieve all registered endpoints (paginated).

netapi ise list-endpoints [--limit <NUM>] [--offset <NUM>]

Example:

# First 100 endpoints
netapi ise list-endpoints --limit 100

# Next 100 (pagination)
netapi ise list-endpoints --limit 100 --offset 100

List Endpoint Groups

Retrieve all endpoint identity groups.

netapi ise list-endpoint-groups

Common Groups: - Blacklist - GuestEndpoints - Profiled - Unknown - Custom groups (e.g., Linux-Research-Onboarding)

Create Endpoint Group

Create a new endpoint identity group.

netapi ise create-endpoint-group <GROUP_NAME> \
  --description "<DESCRIPTION>"

Example:

netapi ise create-endpoint-group "Linux-Research-Onboarding" \
  --description "Linux devices in MAB onboarding phase before EAP-TLS"

Delete Endpoint Group

Remove a custom endpoint identity group from ISE.

netapi ise delete-endpoint-group <GROUP_NAME>

Example:

netapi ise delete-endpoint-group "Old-Test-Group"

Restrictions: - Cannot delete system-defined groups (Profiled, Unknown, Blacklist, etc.) - Cannot delete groups that have endpoints assigned to them - Must first move or delete all endpoints from the group before deletion

Best Practice: Verify no endpoints are using the group:

# List endpoints in the group
netapi ise get-endpoints --group "Old-Test-Group"

# If any exist, move them first
netapi ise update-endpoint-group <MAC> "Different-Group"

dACL Management

Get dACL

Retrieve a downloadable ACL configuration by name.

netapi ise get-dacl <DACL_NAME>

Example:

netapi ise get-dacl "DACL_Linux_Research_EAP_TLS"

Create dACL

Create a new downloadable ACL with specified rules.

netapi ise create-dacl <DACL_NAME> \
  --descr "<DESCRIPTION>" \
  --acl "<ACL_RULES>"

Example (Zero-Trust dACL):

netapi ise create-dacl "DACL_Linux_Research_EAP_TLS" \
  --descr "Zero-trust ACL for Linux EAP-TLS" \
  --acl "
permit udp any host 10.100.11.24 eq 53
permit udp any host 10.100.11.25 eq 53
permit udp any any eq 123
permit tcp any host 10.112.118.141 eq 88
permit tcp any host 10.112.118.141 eq 389
permit tcp any host 10.112.118.141 eq 636
permit tcp any host 10.101.2.131 eq 8443
permit tcp any host 10.101.2.132 eq 8443
permit ip any host 10.134.144.109
permit icmp any any
permit tcp any any eq 80
permit tcp any any eq 443
deny ip any 10.0.0.0 0.255.255.255 log
deny ip any 172.16.0.0 0.15.255.255 log
deny ip any 192.168.0.0 0.0.255.255 log
permit ip any any
"

ACL Ordering Matters!

  • Permit essential services FIRST (DNS, AD, ISE)

  • Block RFC1918 ranges AFTER permits

  • Catch-all permit at end for internet access

Update dACL

Modify an existing dACL’s rules or description.

netapi ise update-dacl <DACL_NAME> \
  --descr "<NEW_DESCRIPTION>" \
  --acl "<NEW_ACL_RULES>"

Delete dACL

Remove a dACL from ISE.

netapi ise delete-dacl <DACL_NAME>

Do not delete dACLs that are referenced by active authorization profiles!

List dACLs

Retrieve all downloadable ACLs.

netapi ise list-dacls

Authorization Profile Management

Get Authorization Profile

Retrieve authorization profile details.

netapi ise get-authz-profile <PROFILE_NAME>

Example:

netapi ise get-authz-profile "Linux_Research_EAP_TLS"

Create Authorization Profile

Create a new authorization profile with dACL, VLAN, and reauth timer.

netapi ise create-authz-profile <PROFILE_NAME> \
  --dacl <DACL_NAME> \
  --vlan <VLAN_ID_OR_NAME> \
  --reauth <SECONDS> \
  --descr "<DESCRIPTION>"

Example:

netapi ise create-authz-profile "Linux_Research_EAP_TLS" \
  --dacl "DACL_Linux_Research_EAP_TLS" \
  --vlan "Research-VLAN" \
  --reauth 28800 \
  --descr "Hardened profile for Linux workstations with EAP-TLS"

Parameters: - --dacl: Downloadable ACL name - --vlan: VLAN ID (e.g., 50) or name (e.g., Research-VLAN) - --reauth: Reauthentication timer in seconds (28800 = 8 hours)

Update Authorization Profile

Modify existing authorization profile.

netapi ise update-authz-profile <PROFILE_NAME> \
  --dacl <NEW_DACL_NAME> \
  --vlan <NEW_VLAN> \
  --reauth <NEW_SECONDS>

Delete Authorization Profile

Remove authorization profile from ISE.

netapi ise delete-authz-profile <PROFILE_NAME>

List Authorization Profiles

Retrieve all authorization profiles.

netapi ise list-authz-profiles

Authorization Rules

Get Authorization Rules

Retrieve all rules in a policy set.

netapi ise get-authz-rules <POLICY_SET_NAME>

Example:

# MAB policy set
netapi ise get-authz-rules "Wired Closed MAB"

# DOT1X policy set
netapi ise get-authz-rules "Wired Closed DOT1X"

Add Authorization Rule

Add a new authorization rule to a policy set.

netapi ise add-authz-rule <POLICY_SET> <RULE_NAME> <AUTHZ_PROFILE> \
  [--condition "<CONDITION>"] \
  [--rank <POSITION>]

Example (Endpoint Group Condition):

netapi ise add-authz-rule "Wired Closed MAB" \
  "Linux_Research_Onboard" \
  "Research_Onboard" \
  --condition "IdentityGroup:Name EQUALS Endpoint Identity Groups:Linux-Research-Onboarding" \
  --rank 5

Example (AD Group Condition):

netapi ise add-authz-rule "Wired Closed DOT1X" \
  "Linux_Research_EAP_TLS_Rule" \
  "Linux_Research_EAP_TLS" \
  --condition "INSIDE-AD:ExternalGroups CONTAINS inside.domusdigitalis.dev/Groups/Research/GRP-Research-Linux-Workstations" \
  --rank 3

Rank/Position: Lower numbers = higher priority. ISE evaluates rules top-to-bottom.

Update Authorization Rule

Modify existing authorization rule.

netapi ise update-authz-rule <POLICY_SET> <RULE_NAME> \
  [--profile <NEW_AUTHZ_PROFILE>] \
  [--condition "<NEW_CONDITION>"] \
  [--rank <NEW_POSITION>]

Delete Authorization Rule

Remove authorization rule from policy set.

netapi ise delete-authz-rule <POLICY_SET> <RULE_NAME>

Network Device Management

Get Network Device

Retrieve NAD (Network Access Device) configuration.

netapi ise get-nad <DEVICE_NAME_OR_IP>

Create Network Device

Register a new network device (switch, WLC, etc.) in ISE.

netapi ise create-nad <DEVICE_NAME> \
  --ip <IP_ADDRESS> \
  --shared-secret <RADIUS_SECRET> \
  [--group <DEVICE_GROUP>]

Example:

netapi ise create-nad "SRT-9-9300" \
  --ip "10.238.179.1" \
  --shared-secret "strong_radius_secret_here" \
  --group "Location#All Locations#SRT Building"

List Network Devices

Retrieve all registered network devices.

netapi ise list-nads

Identity Store Management

Get AD Join Point

Retrieve Active Directory join point configuration.

netapi ise get-ad-join <JOIN_POINT_NAME>

Example:

netapi ise get-ad-join "INSIDE-AD"

List AD Join Points

Retrieve all AD join points configured in ISE.

netapi ise list-ad-joins

Get AD Groups

Retrieve groups from a specific AD join point.

netapi ise get-ad-groups <JOIN_POINT_NAME>

Example:

netapi ise get-ad-groups "INSIDE-AD"

Use Case: Verify AD group names before using in authorization conditions.

Common Workflows

Workflow 1: Endpoint Onboarding (MAB)

# Step 1: Create endpoint group
netapi ise create-endpoint-group "Linux-Research-Onboarding" \
  --description "Linux devices in onboarding phase"

# Step 2: Create permissive dACL
netapi ise create-dacl "DACL_Research_Onboard" \
  --descr "Permissive onboarding policy" \
  --acl "permit udp any any eq 53
permit tcp any any eq 88
permit tcp any any eq 389
permit tcp any any eq 443
permit ip any any"

# Step 3: Create authorization profile
netapi ise create-authz-profile "Research_Onboard" \
  --dacl "DACL_Research_Onboard" \
  --vlan "Research-VLAN" \
  --reauth 28800

# Step 4: Add authz rule to MAB policy
netapi ise add-authz-rule "Wired Closed MAB" \
  "Linux_Research_Onboard" \
  "Research_Onboard" \
  --condition "IdentityGroup:Name EQUALS Endpoint Identity Groups:Linux-Research-Onboarding"

# Step 5: Pre-register endpoint
netapi ise create-endpoint b4:e9:b8:f6:c8:17 \
  --group "Linux-Research-Onboarding" \
  --description "chlxsbg - Onboarding"

Workflow 2: Migration to EAP-TLS

# Step 1: Create hardened dACL (zero-trust)
netapi ise create-dacl "DACL_Linux_Research_EAP_TLS" \
  --descr "Zero-trust ACL" \
  --acl "<zero-trust-rules>"

# Step 2: Create hardened authz profile
netapi ise create-authz-profile "Linux_Research_EAP_TLS" \
  --dacl "DACL_Linux_Research_EAP_TLS" \
  --vlan "Research-VLAN" \
  --reauth 28800

# Step 3: Add authz rule to DOT1X policy
netapi ise add-authz-rule "Wired Closed DOT1X" \
  "Linux_Research_EAP_TLS_Rule" \
  "Linux_Research_EAP_TLS" \
  --condition "AD-GROUP-CONDITION-HERE"

# Step 4: Update endpoint group
netapi ise update-endpoint b4:e9:b8:f6:c8:17 \
  --group "Linux-Research-Production"

# Step 5: Force reauthentication (see MnT API docs)
netapi ise mnt coa b4:e9:b8:f6:c8:17

Error Handling

Common Errors

401 Unauthorized:

Check ISE_API_USER and ISE_API_PASS credentials
Verify ERS API is enabled in ISE

404 Not Found:

Resource doesn't exist
Check spelling of dACL/profile/endpoint names

409 Conflict:

Resource already exists
Use update instead of create
Or delete existing resource first

500 Internal Server Error:

ISE configuration error
Check ISE logs: /opt/CSCOcpm/logs/
Verify ACL syntax if creating dACL

Best Practices

  1. Always use dsec for credentials - Never hardcode secrets

  2. Test dACLs in onboarding first - Before applying to production

  3. Use descriptive names - Include purpose/environment in names

  4. Document ACL ordering - Comment critical permit statements

  5. Monitor after changes - Use MnT API to verify sessions

  6. Backup before major changes - Export configs regularly

  7. Use endpoint groups - Don’t hardcode MAC addresses in rules

  8. Follow naming conventions - Consistent prefixes (DACL_, Linux_, etc.)

See Also

netapi Documentation