REST APIs for 24.5

Login Service authentication token you obtained using the Login Users API.

Login Users API JSON Schema

This API uses the Illumio Core schema users_login_get.schema.json.

curl -i -X GET https://pce.my-company.com:8443/api/v2/users/login -H "Authorization: Token token=ntqz5jUrI2guA1XzUiLCJlbmMiOiJBMTI4Q0JDLUhZJ" 

GET /users/login returns a temporary auth_username and session_token.

These are used in the curl examples as $KEY:$TOKEN respectively (if you're not using persistent API credentials).

Example: -u user_4:'xxxxxxxx628f5773c47b72dbcd437b4a10d85a06a'

{
    "full_name": "Buford T. Justice",
    "local": true,
    "type": "local",
    "href": "/users/4",
    "auth_username": "user_4",
    "inactivity_expiration_minutes": 10,
    "start": "2017-10-12 16:49:49 UTC",
    "time_zone": "America/Los_Angeles",
    "last_login_ip_address": "209.37.96.18",
    "last_login_on": "2020-10-12T16:49:49.000Z",
    "certificate": {
        "expiration": "2020-11-27T03:09:00.000Z",
        "generated": false
    },
    "login_url": "https://devtest166.ilabs.io:8443/login",
    "orgs": [
        {
            "org_id": 1,
            "org_href": "/orgs/1",
            "display_name": "illum.io",
            "role_scopes": [
                {
                    "role": {
                        "href": "/orgs/1/roles/owner"
                    },
                    "scope": [],
                    "href": "/orgs/1/users/4/role_scopes/4"
                }
            ]
        }
    ],
    "session_token": "xxxxxxxx628f5773c47b72dbcd437b4a10d85a0",
    "version_tag": "60.1.0-9701f78bef46f521e3d6dd98f70cd8c220940885",
    "version_date": "Tue Sep 12 11:12:46 2020 -0700",
    "product_version": {
        "version": "17.1.1",
        "build": "6168",
        "long_display": "17.1.1-6168",
        "short_display": "17.1.1"
    }
}

Optional Feature Schema: optional_feature.schema.json

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "object",
	"additionalProperties": false,
	"description": "PCE Feature",
	"required": [
		"name",
		"enabled"
		],
	"properties": {
		"name": {
			"type": "string",
			"description": "The name of the feature"
		},
		"preview": {
			"type": "boolean",
			"description": "Is this a preview feature"
		},
		"enabled": {
			"type": "boolean",
			"description": "Is this feature enabled"
		}
	}
}

Get the optional features collection: optional_features_get

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "array",
	"items": {
			"$ref": "optional_feature.schema.json"
		}
	}

Set the optional features for an organization: optional_features_put

The example shows the properties available in the release 24.1.1, which includes the property rule_based_label_mapping.

This property was added to support the new APIs presented in Rule-Based Label Mapping.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "array",
    "items": {
	   "oneOf": [
		{
		"type": "object",
		"additionalProperties": false,
		"required": [
		    "name",
		    "enabled"
		],
		"properties": {
		    "name": {
			"description": "Name of the feature",
			"type": "string",
			"enum": [
				"ip_forwarding_firewall_setting",
				"ui_analytics",
				"illumination_classic",
				"ransomware_readiness_dashboard",
				"per_rule_flow_log_setting",
				"lightning_default",
				"collector_scanner_filters",
				"corporate_ips_groups",
				"labels_editing_warning_for_enforcement_mode",
				"label_based_network_detection",
				"cloudsecure_enabled",
				"windows_outbound_process_enforcement",
				"rule_based_label_mapping"
			]
		},
		"enabled": {
		    "description": "Enable or disable this feature",
		    "type": "boolean"
		}
	   }
	},
	{
	    "type": "object",
	    "additionalProperties": false,
	    "required": [
	        "name",
		"enabled"
	    ],
	    "properties": {
		"name": {
		    "description": "Name of the feature",
		    "type": "string",
		    "enum": [
			"editable_dns_client_rule",
			"editable_dhcp_client_rule"
		    ]
		},
		"enabled": {
		    "description": "Enable or disable this feature",
		    "type": "boolean"
		},
		"key": {
		    "description": "Key required to enable the feature. Contact Illumio Support for more details.",
				"type": "string"
			    }
			}
		    }
		]
	    }
	}

To create an authentication token and authenticate with the Login Service, you need to specify the Fully Qualified Domain Name (FQDN) of the PCE you want to access in the call.

When you received your invitation, you used an e-mail and password to create your PCE account. Use these credentials now to make a call to authenticate.

If you haven't received an invitation, contact your Illumio administrator.

Example (local users only, use SAML ID for remote users):

You also need the FQDN of the Login Server plus the FQDN of the PCE host you want to access:

Analytics opt-out

The property configurable_label_dimension was added so that the UI users can determine if an organization has enabled user analytics.

Analytics is opt-in by default. If it has been disabled, the UI does not track analytics for that organization.

To set or clear the optional analytics feature, use:

{ 
name: "ui_analytics", enabled: false|true 
}

Illumination Classic opt-out

The property illumination_classic is added to enable or disable the use of that feature.

To set or clear the optional Illumination Classic feature, use:

{ 
name: "illumination_classic", enabled: false|true 
}

The APIs

require that one of the following optional features is enabled :

In addition, both APIs are implementing the input validation on payload content:

The example response for the API optional_features_put with the label_based_network_detection enabled:

"illumination_classic",
		"ransomware_readiness_dashboard",
		"per_rule_flow_log_setting",
		"lightning_default",
		"label_based_network_detection"
		]
	},
	"enabled": {

In releases 23.2.10 and 23.4, for the required property name a new optional feature flag for label editing was added: labels_editing_warning_for_enforcement_mode.

To enable or disable this flag, use the following CURL command:

curl -u ${your_api_key}: ${your_api_secret} -H "Content-Type: application/json" -X PUT -d '[{"name":"labels_editing_warning_for_enforcement_mode","enabled":true}]' https://${your_pce_server}:8443/api/v2/orgs/${your_ord_id}/optional_features
	

In release 23.5, an optional feature flag for the Windows outbound process was added: windows_outbound_process_enforcement.

This feature flag can be enabled or disabled using the following CURL command:

curl -u ${your_api_key}: ${your_api_secret} -H "Content-Type: application/json" -X PUT -d '[{"name":"windows_outbound_process_enforcement","enabled":true}]' https://${your_pce_server}:8443/api/v2/orgs/${your_ord_id}/optional_features
		

where you can define the part of the command: "enabled":true or "enabled":false.