Walkthrough of Endpoints and Groups

The following endpoint can be used to obtain a JWT Token:

http://localhost:43470/api/v2/Authentication/Login

JSON Request Body

JSON Response

The JWT Expires after 15 minutes, a new JWT must be generated for further usage.

First let's test you have everything setup correctly by requesting a list of the endpoints in your environment. Enter this call into your browser:

http://localhost:43470/api/v2/Endpoints

The result is a JSON document containing information about the Endpoints.

Depending on the browser you use, you may be prompted to download the file.

You can also get the above URL from the Swagger docs:

1. Expand Endpoints > GET /api/v2/Endpoints.
   

2. Click Try it out!
   The URL appears in the Request URL field.
   

3. Click Model to view descriptions of the parameters returned in the Response Body.
   

If you examine the list of endpoints from your previous request you'll see that they each have a GUID (Global Unique Identifier) property. This is the key for the Endpoint entity.

Many API operations use entity keys to identify individual entities. Keys are usually integers or unique identifiers (GUIDs).

Copy the GUID for one endpoint from the result of the previous call (without the quotes) and use it in the next call. We'll use the one highlighted above:

http://localhost:43470/api/v2/Endpoints(8a6f1210-0b15-4da1-8ef9-d3b155d31d58)

JSON-response, with line breaks inserted for clarity

OData provides a rich query language for selecting and filtering entity collections using keywords such as select, filter, orderby, top and skip.

You can get more information about OData 4.0 in OData Getting Started and OData Version 4.0 Documentation. We recommend consulting the ODataVersion 3.0 Documentation, which is better documented at the moment.

If you apply a select query to your previous call you can limit the JSON response to only contain the endpoint's name and IP Address.
This is done by adding a question mark (?) , select query keyword ($select) and then a comma separated list of the properties (Name,IpAddress):

http://localhost:43470/api/v2/Endpoints(8a6f1210-0b15-4da1-8ef9-d3b155d31d58)?$select=Name,IpAddress

JSON-response, with line breaks inserted for clarity:

Again the Swagger docs can help you configure the URL:

1. Expand Endpoints > GET /api/v2/Endpoints({Guid}).
   

2. In the Parameters section, enter the values for Guid and $select.
   

3. Click Try it out!
   

A call to retrieve the Groups entity collection returns all of the groups in the IvantiEndpoint Security database, including the system and parent groups:

http://localhost:43470/api/v2/Groups

If you apply a filter query to your previous call you can limit the JSON-response to only see groups created by a User. This is done by adding a question mark (?), followed by the filter query keyword ($filter=) and then a filter predicate (Type eq 'User'):

http://localhost:43470/api/v2/Groups?$filter=Type eq 'User'

The first “User” group listed in the JSON result is the parent group for all custom groups. This usually has an Id of 4. If you have not created any custom groups you will only see this group.

JSON-response, with line breaks inserted for clarity:

You make a new custom group by creating a request that will POST data to the API in the form of JSON. This cannot be done by entering a URL in a browser. It can be achieved using the Swagger doc, but using a tool with the ability to create URL requests with specific headers and message bodies is recommended.

The Postman extension for Google Chrome is specifically made for this task and is easy to use.

Use the JSON-response from the Groups request as a guide to create a new object.
Have a look at the parameters in the Swagger docs. Click Model to review the descriptions of the properties that can be specified in the groups parameter.

You must specify the name, description and where the Group sits in the custom group hierarchy. This is the same information as is required during normal Group creation in the Endpoint Security Web User Interface.
The rest of the properties are marked as optional.

To make the request using Postman, set the following in the Postman app:

1. Select the Request Type POST.
2. Enter the URL: http://localhost:43470/api/v2/Groups
3. On the Body tab (a), select raw (b) and JSON (c).
4. Enter the body:

   {

   "Name": "REST group",
   "Path": ,
   "Description": "My new group likes REST APIs"

   }

   The result of steps 1 through 4 should look like this:
   

5. Click Send.
   A response status of 201 Created to will indicate success.
   

You can now navigate to the IvantiEndpoint SecurityGroups page to confirm your group was created:

1. In the Endpoint Security Console, go to Manage > Groups.

2. In the Groups browser, expand the Custom Groups node.
   

You can add one or more endpoints to your new custom group. This is another POST request.
If you have a look at the Swagger docs you will see that the call takes the form:

POST http://localhost:43470/api/v2/Groups({id})/Endpoints ({endpointGuid})

You can obtain the necessary group id and endpoint guid using previously discussed API calls.

Here’s something you can try to prove the usefulness of the Groups API.

Try setting up various custom groups that suit the topology of your endpoint network (e.g. “Finance”, “IT” and “Sales”) and assign them policies in the Endpoint Security Console for the modules they are installed with.

Now these policies will be applied to the endpoint automatically after the API call is made to add it to the correct group.