Overview

REST methods determine the HTTP method for manipulating the resources defined in the service operation. The kind of operations available include those predefined by the HTTP verbs GET, POST, PUT, DELETE and so on. The response may confirm that some alteration has been made to the stored resource, and it may provide hypertext links to other related resources or collections of resources. By making use of a stateless protocol and standard operations, REST systems aim for fast performance, reliability, and the ability to grow, by re-using components that can be managed and updated without affecting the system as a whole, even while it is running.

REST API Support for ICS involves only Configuration APIs. Also, ICS supports only the GET, POST, PUT and DELETE APIs.

The valid and supported values are described in the following Valid and Supported Values table:

HTTP Verb	Definition
DELETE	Delete an existing resource.
GET	Retrieve a representation of a resource.
POST	Create a new resource
PUT	Create a new resource to a new URL or modify an existing resource to an existing URL.

The error codes supported are described in the following Error Codes Supported table:

HTTP Verb	Definition
200 OK	Requesting for resource information successful using GET Resource update successful using PUT
201 Created	Resource creation successful using POST
204 No Content	Deletion of resource successful with no body. Even PUT, POST may return 204 if no errors or warnings seen
400 – Bad Request	Any Request (GET/PUT/POST/DELETE, and so on) is invalid.Example: Incorrect JSON format
401 – Unauthorized	Any REST Call with invalid credentials
403 – Forbidden	REST Call with valid credentials but no permission
404 – Not found	Requested resource in URI does not exist
422 – Unprocessable Entity	Any validation/referential integrity errors that would result in failure of PUT/POST/DELETE request
500 Server Error	When ICS rest server is not responding

URL Encoding

A URL can be from a limited set of characters belonging to the US-ASCII character set. Characters outside these character set are not allowed to be placed directly within URLs, but their encoded value preceded by % can be used in the URLs.

The following table demonstrates URL Encoding:

Character	URL Encoding (UTF-8)
<space>	%20
#	%23
$	%24
%	%25
&	%26
*	%2A
/	%2F
@	%40
\	%5C

Example:

•To get active session details of user “admin user”

curl -k -u <api-key>: https://<pcs-ip>/api/v1/system/activeusers?name= admin%20user

•To get active session details of user “admin@user”

curl -k -u <api-key>: https://<pcs-ip>/api/v1/system/activeusers?name= admin%40user

For more details, refer https://www.urlencoder.io/learn/.

Authentication for REST APIs

Basic authentication using the HTTP authorization header is used to authenticate username/password on the Administrators auth server. It is expected that the user is already configured in the Administrators auth server. On a successful login, a random token (api_key) is generated once and sent back as a JSON response. Further access to APIs can use this api_key value as username and password as empty in their Authorization header for access.

A new random api_key is generated on a successful login. The user can continue to use this key till the administrator:

•Enables/disables the user account

Ivanti recommends using api/v1/realm_auth instead of api/v1/auth as it will not be supported from 22.7R2.1 release onwards. Update/Modify your REST based scripts to make use of /api/v1/realm_auth.

The generated api_key is valid until the session timeout configured in Admin roles and mapped to the admin realm. After expiration, users can regenerate the api_key using api/v1/realm_auth.

Realm-based Authentication (Recommended)

Ivanti recommends realm-based authentication instead of basic authentication using the HTTPS authorization header.

/api/v1/realm_auth supports login via REST API on a particular admin realm with following:

•MFA not enabled

•SAML or oAuth not supported as Primary Auth

Supported authservers are :

•Administrators(local authserver)

•AD

•LDAP

•RADIUS

Copy

Request
    POST /api/v1/realm_auth HTTP/1.1
    Host: xx.xxx.xxx.xxx
    Content-Type: application/json
    Authorization: Basic YWRtaW46ZGFuYTEyMw==
    {
      "realm": "adminrealm"
    }
Response
    HTTP/1.1 200 OK
    content-type →application/json
    {
        "api_key": "NjQzOGU0N2I5MDUyMWZhZWM0NmZiMTMxY2U3M2YyM2Q="
    }

Authorization header for all future requests should perform Basic Auth using above api_key value as username and password as empty.

Copy

Request
    GET /api/v1/configuration HTTP/1.1
    Host: xx.xxx.xxx.xxx
    Authorization: Basic cDVtTWxjN1JRdTgxUjJOdnNzTENDWmhQMDVrZjBOMk9ORmVZZUxYWDZhVT06
Response
HTTP/1.1 200 OK
Content-Length →283
Content-Type →application/json
{
    "administrators":
    { "href": "/api/v1/configuration/administrators" }
    ,
    "authentication":
    { "href": "/api/v1/configuration/authentication" }
    ,
    "system":
    { "href": "/api/v1/configuration/system" }
    ,
    "users":
    { "href": "/api/v1/configuration/users" }
}

Sample GET/POST/PUT/DELETE Request and Responses in ICS

Below is a sample of GET/POST/PUT/DELETE request and responses:

GET API Call: Fetch the Specific User under Local Authentication Server

Copy

Request
    GET /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user/user0001 HTTP/1.1
    Host: xx.xxx.xxx.xxx
    Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06
    Content-Type: application/json
Response
    HTTP/1.1 200 OK
    Content-Length: 309
    Content-Type: application/json
{
    "change-password-at-signin": "false",
    "console-access": "false",
    "enabled": "true",
    "fullname": "user0001",
    "one-time-use": "false",
    "password-cleartext": "'xxxxxxx",
    "username": "user0001"
}

Equivalent Curl Command

Copy

Command
    curl -i -u p9/h85ytEmkDzvkGSmQ4z77p6Ya7aLIC42vh0F9CGaQ=: -X GET https://<hostname>/api/v1/configuration/authentication/auth-servers/auth-server/System%20Local/local/users/user/user0001
    Response
    HTTP/1.1 200 OK
    Content-Type: application/json
    Content-Length: 303
{
  "change-password-at-signin": "false",
  "console-access": "false",
  "enabled": "true",
  "fullname": "user0001",
  "one-time-use": "false",
  "password-cleartext": "'xxxxx",
  "username": "user0001"
}

POST API Call: Create User for Existing Local Authentication Server

Copy

Request
    POST /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user HTTP/1.1
    Host: xx.xxx.xxx.xxx
    Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06
    Content-Type: application/json
{
  "change-password-at-signin": "false",
  "console-access": "false",
  "enabled": "true",
  "fullname": "user0001",
  "one-time-use": "false",
  "password-cleartext": "'xxxxx",
  "username": "user0001"
}
Response
    HTTP/1.1 200 OK
    Content-Length: 122
    Content-Type: application/json
{
    "result": {
        "info": [
            {
                "message": "Operation succeed without warning or error!"
            }
        ]
    }
}

Equivalent Curl Command

Copy

Command
    curl -i -u hv5uaqOWF5kuISVnUiGEabOL8fsczsK98zVwpHYWgKE=: -X POST https://<hostname>/api/v1/configuration/authentication/auth-servers/auth-server/System%20Local/local/users/user -H 'Content-Type: application/json' -d '{"change-password-at-signin": "false", "console-access": "false", "enabled": "true", "fullname": "user0001", "one-time-use": "false", "password-cleartext": "'xxxxxxx", "username": "user0002"}'

Response
    HTTP/1.1 201 CREATED
    Content-Type: application/json
    Content-Length: 128
 
{
  "result": {
    "warnings": [
      {
        "message": "The configuration has been implicitly changed"
      }
    ]
  }
}

PUT API Call: Update Full name field of Specific user

Copy

Request
    PUT /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user/user0001/fullname HTTP/1.1
    Host: xx.xxx.xxx.xxx
    Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06
    Content-Type: application/json
    Cache-Control: no-cache
{
  "fullname":"REST API test for user0001"
}
Response
    HTTP/1.1 200 OK
    Content-Length: 122
    Content-Type: application/json
{
  "result": {
    "info": [
      {
        "message": "Operation succeed without warning or error!"
      }
    ]
  }
}

Equivalent Curl Command

Copy

Command
    curl -i -u hv5uaqOWF5kuISVnUiGEabOL8fsczsK98zVwpHYWgKE=: -X PUT https://<hostname>/api/v1/configuration/authentication/auth-servers/auth-server/System%20Local/local/users/user/user0001/fullname -H 'Content-Type: application/json' -d '{"fullname": "user0001"}'
Response
    HTTP/1.1 200 OK
    Content-Type: application/json
    Content-Length: 124
{
  "result": {
    "info": [
      {
        "message": "Operation succeeded without warning or error!"
      }
    ]
  }
}

After updating, fetch the User details and observe the fullname field updated:

Copy

Request
    GET /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user/user0001 HTTP/1.1
    Host: xx.xxx.xxx.xxx
    Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06
    Content-Type: application/json
Response
    HTTP/1.1 200 OK
    Content-Length →327
    Content-Type →application/json
{
  "change-password-at-signin": "false", 
  "console-access": "false", 
  "enabled": "true", 
  "fullname": "REST API test for user0001", 
  "one-time-use": "false", 
  "password-cleartext": "'xxxxxxx", 
  "username": "user0001"
}

DELETE API Call: DELETE Specific User

Copy

Request
    DELETE /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user/user0001 HTTP/1.1
    Host: xx.xxx.xxx.xxx
    Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06
    Content-Type: application/json
Response
    HTTP/1.1 200 OK
    Content-Length →122
    Content-Type →application/json
{
  "result": {
    "info": [
      {
        "message": "Operation succeed without warning or error!"
      }
    ]
  }
}

Equivalent Curl Command

Copy

Command
    curl -i -u hv5uaqOWF5kuISVnUiGEabOL8fsczsK98zVwpHYWgKE=: -X DELETE https://<hostname>/api/v1/configuration/authentication/auth-servers/auth-server/System%20Local/local/users/user/user0002/
Response
    HTTP/1.1 204 NO CONTENT
    Content-Type: application/json
    Content-Length: 0

After deleting, try to fetch the resource and you would observe 404 response.

Copy

Request
    GET /api/v1/configuration/authentication/auth-servers/auth-server/Sys-Local/local/users/user/user0001 HTTP/1.1
    Host: xx.xxx.xxx.xxx
    Authorization: Basic cDkvaDg1eXRFbWtEenZrR1NtUTR6NzdwNllhN2FMSUM0MnZoMEY5Q0dhUT06
    Content-Type: application/json
    Cache-Control: no-cache
Response
    404 NOT FOUND
    Content-Length: 105
    Content-Type: application/json
{
  "result": {
    "errors": [
      {
        "message": "Resource does not exist."
      }
    ]
  }
}

Representing Configuration Resources Using Links

When performing a GET request on a configuration resource, the json response may have "href" attributes to represent smaller resources within.

Copy

As an example, "GET /api/v1/configuration" returns:
{
  "users": {
    "href": "/api/v1/configuration/users"
  },
  "system": {
    "href": "/api/v1/configuration/system"
  },
  "authentication": {
    "href": "/api/v1/configuration/authentication"
  },
  "administrators": {
    "href": "/api/v1/configuration/administrators"
  }
}

The href values can be used to access smaller resources.

Sample GET/POST/PUT/DELETE Request and Responses in IPS

Below is a sample of GET/POST/PUT/DELETE request and responses:

GET API Call: Fetch the Details under Endpoint Policy

This example shows how to fetch the details under endpoint policy in IPS.

Copy

Request
GET /api/v1/configuration/uac HTTP/1.1
 
Host xx.xx.xx.xx
 
Authorization: Basic
VU9qSTlGTzNrYVk5d0t2aXpBN1dPZ0FyZlN1S3FmTkNnQUh0R0ZuR0xSbz06
 
Content-Type: application/json
 
{
    "admissionControl": {
        "href": "/api/v1/configuration/uac/admissionControl"
    },
    "host-enforcer": {
        "href": "/api/v1/configuration/uac/host-enforcer"
    },
    "infranet-enforcer": {
        "href": "/api/v1/configuration/uac/infranet-enforcer"
    },
    "mac-address-realms": {
        "href": "/api/v1/configuration/uac/mac-address-realms"
    },
    "network-access": {
        "href": "/api/v1/configuration/uac/network-access"
    },
    "snmpEnforcement": {
        "href": "/api/v1/configuration/uac/snmpEnforcement"
    }
}
Response
HTTP/1.1 200 OK
 
Content-Length: 340
 
Content-Type: application/json

Equivalent Curl Command

Copy

Command
curl -i -u g4dncT4699c+IWip/+8urgXM0Luy1vQdj9zNxEFWEbM=: -X GET https://<hostname>/api/v1/configuration/uac

Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 620
{
  "admissionControl": {
    "href": "/api/v1/configuration/uac/admissionControl"
  },
  "host-enforcer": {
    "href": "/api/v1/configuration/uac/host-enforcer"
  },
  "infranet-enforcer": {
    "href": "/api/v1/configuration/uac/infranet-enforcer"
  },
  "mac-address-realms": {
    "href": "/api/v1/configuration/uac/mac-address-realms"
  },
  "network-access": {
    "href": "/api/v1/configuration/uac/network-access"
  },
  "networkDeviceAdministration": {
    "href": "/api/v1/configuration/uac/networkDeviceAdministration"
  },
  "snmpEnforcement": {
    "href": "/api/v1/configuration/uac/snmpEnforcement"
  }

POST API Call: Create an SRX Enforcer in Infranet Enforcer Connection

This example shows how to create an SRX Enforcer in Infranet Enforcer connection.

Copy

Request
    POST /api/v1/configuration/uac/infranet-enforcer/connections/infranet-enforcer/ HTTP/1.1
    Host xx.xx.xx.xx
    Authorization: Basic
    VU9qSTlGTzNrYVk5d0t2aXpBN1dPZ0FyZlN1S3FmTkNnQUh0R0ZuR0xSbz06
    Content-Type: application/json
{
    "idp-for-local-sessions-only": "true",
    "junos": {
        "location-group": "- No 802.1X -",
        "password-encrypted": "3u+UR6n8AgABAAAAofSnIBrU19vdwUslG5LG4cg1QH6CbXDSmY4ZW0x85HY="
    },
    "name": "SRX",
    "serial-number": [
        "SJFIOQJI4KNM"
    ],
    "severity-filter": "medium",
    "use-idp": "false"
}
Response
HTTP/1.1 201 OK
Content-Length: 122
Content-Type: application/json
{
    "result": {
    "info": [
    {
      "message": "Operation succeed without warning or error!"
    }
   ]
  }
}

Equivalent Curl Command

Copy

Command
curl -i -u g4dncT4699c+IWip/+8urgXM0Luy1vQdj9zNxEFWEbM=: -X POST https://<hostname>/api/v1/configuration/uac/infranet-enforcer/connections/infranet-enforcer -H 'Content-Type: application/json' -d '{"idp-for-local-sessions-only": "true", "junos": { "location-group": "- No 802.1X -", "password-encrypted":"3u+UR6n8AgABAAAAofSnIBrU19vdwUslG5LG4cg1QH6CbXDSmY4ZW0x85HY=" },"name": "SRX","serial-number": ["SJFIOQJI4KNM"],"severity-filter": "medium", "use-idp": "false"}'

Response
HTTP/1.1 201 CREATED
 
Content-Type: application/json
Content-Length: 124
 
{
  "result": {
    "info": [
      {
        "message": "Operation succeeded without warning or error!"
      }
    ]
  }
}

PUT API Call: Update Existing Configuration Where In Initial Location Group is Configured as Guest

This example updates the existing configuration where in the initial Location Group is configured as "Guest" and then later updated to "Default" Location group.

Before Updating the Location Group

Copy

Request
GET api/v1/configuration/uac/network-access/radius-clients/radius-client/Radius%20Client HTTP/1.1
Host xx.xx.xx.xx
Authorization: Basic
VU9qSTlGTzNrYVk5d0t2aXpBN1dPZ0FyZlN1S3FmTkNnQUh0R0ZuR0xSbz06
Content-Type: application/json
{
    "location-group": "Guest",
    "name": "Radius Client",
}
Response
HTTP/1.1 200 OK
Content-Length: 122
Content-Type: application/json

Equivalent Curl Command

Copy

Command
curl -i -u g4dncT4699c+IWip/+8urgXM0Luy1vQdj9zNxEFWEbM=: -X PUT https://<hostname>/api/v1/configuration/uac/network-access/radius-clients/radius-client/Radius%20Client -H 'Content-Type: application/json' -d '{"location-group": "Default","name": "Radius Client"}’

Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 124
{
  "result": {
    "info": [
      {
        "message": "Operation succeeded without warning or error!"
      }
    ]
  }
}

After Updating the Location Group

Copy

Request
PUT api/v1/configuration/uac/network-access/radius-clients/radius-client/Radius%20Client HTTP/1.1
Host xx.xx.xx.xx
Authorization: Basic
VU9qSTlGTzNrYVk5d0t2aXpBN1dPZ0FyZlN1S3FmTkNnQUh0R0ZuR0xSbz06
Content-Type: application/json
{
 "location-group": "Default",
    
    "name": "Radius Client",
    
}
Response
HTTP/1.1 200 OK
Content-Length: 122
Content-Type: application/json
{
 "result": {
        "info": [
            {
                "message": "Operation succeed without warning or error!"
            }
        ]
    }
}

DELETE API Call: Delete an SNMP Device

This example shows how to delete SNMP device from IPS.

Copy

Request
    DELETE api/v1/configuration/uac/snmpEnforcement/clients/client/ruckus HTTP/1.1
    Host xx.xxx.xxx.xxx
    Authorization: Basic
    VU9qSTlGTzNrYVk5d0t2aXpBN1dPZ0FyZlN1S3FmTkNnQUh0R0ZuR0xSbz06
    Content-Type: application/json
Response
    HTTP/1.1 204 NO CONTENT
    Content-Length: 0
    Content-Type: application/json

Equivalent Curl Command

Copy

Command
    curl -I -u g4dncT4699c+IWip/+8urgXM0Luy1vQdj9zNxEFWEbM=: -X DELETE https://<hostname>/api/v1/configuration/uac/snmpEnforcement/clients/client/ruckus
Response
    HTTP/1.1 204 NO CONTENT
    Content-Type: application/json
    Content-Length: 0