Skip to main content

REST APIs 25.1 Developer Guide

Authentication

Before you can use the Illumio REST API to access the PCE, you need to use the Login Users API to authenticate with the Illumio Login Service and obtain an authentication token.

Authenticate to Login Service

Before using the Illumio REST API to access the PCE, you need to use the Login Users API to authenticate with the Illumio Login Service and obtain an authentication token. This authentication token expires in 30 seconds.

The URL for the Illumio Login Service for Illumio Core Cloud users is:

  • Login Server: https://login.illum.io:443

  • PCE: scp1.illum.io

For SaaS customers, the PCE URL can be different based upon their SaaS PCE:

  • SCP1 & SCP2 (US)

  • SCP3 UK only

  • SCP4 APAC

  • SCP5 (EMEA)

If you have deployed the PCE as software, then the hostname for the PCE is the value you defined for the 'pce_fqdn' parameter in the runtime_env.yml file.

Once obtained, you can pass the authentication token to the PCE you want to access using the Login API. Once you have authenticated with the PCE and received a session token, you can make other API calls or create an API Key for persistent API access to the PCE.

URI to Authenticate with the Login Service

POST [api_version]/login_users/authenticate
Create an Authentication Token for the Login Service

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.

Parameter

Description

Type

Required

pce_fqdn

Fully Qualified Domain Name (FQDN) of the PCE

If you are using Illumio Core Cloud, then the FQDN for the PCE is scp1.illum.io.

If you have deployed the PCE virtual appliance in your network, then use the FQDN specified during installation of the PCE virtual appliance.

String

Yes

Curl Commands for Authentication

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:

  • The Login Server FQDN for Illumio Core Cloud users is https://login.illum.io:443

  • The PCE FQDN is scp1.illum.io

Note

The authorization token returned (auth_token) expires after being idle for 30 seconds. Be ready to call GET users/login to create session credentials immediately after making the call to login_users/authenticate.

Optional Features

This API was introduced to help avoid issues with misconfigured DNS, which can cause problems with VEN connectivity. Likewise, misconfiguring DHCP can cause problems with IP addresses.

You need a key to invoke /optional_features API to enable editable_dns_client_rule or editable_dhcp_client_rule. Such a key involves a portion that is tightly controlled so that it cannot be randomly generated.

Once the key is generated, it cannot be used in more than one place, meaning an API call provided to customer #1 cannot be replayed at customer #2 who must request their key.

An example of the generated key:

secret = 
		'...'   # value embedded in code 
 
data = Base64.strict_encode64({ 
	'pce_fqdn'   => Illumio::RuntimeEnvironment.pce_fqdn, 
	'org_id'   => xorg_id, 
	'optional_feature'   => 
	'editable_dns_client_rule' , 
	'not_valid_after'   => Time.now.utc.iso8601 
}) 
 
key = data + OpenSSL::HMAC.hexdigest( 'SHA256' , secret, data)
Setting Optional Features

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 
}
Label-Based Network Detection

The APIs

  • POST /api/v2/orgs/{org_id}/networks

  • PUT /api/v2/orgs/{org_id}/networks/:network_id

require that one of the following optional features is enabled :

  • label_based_network_detection

  • cidr_network_detection_enabled

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

  • If the cidrs field is provided, the optional feature cidr_network_detection_enabled must be set.

  • If the scopes field is provided, the optional feature label_based_network_detection must be enabled.

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": {
labels_editing_warning_for_enforcement_mode

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
windows_outbound_process_enforcement

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.