1. Elisity
  2. Cloud Control Center
  3. API

How to Access Elisity APIs

Avatar
Taylor Colwell


This guide serves as an introduction to accessing Elisity APIs and relevant documentation.

To set up identity-based access controls for API endpoints, please review our guide to Setting Up Identity and Access Management (IAM) Using Role-Based Access Control (RBAC) in Cloud Control Center. 

 

Introduction

Elisity offers customers the option to leverage APIs for integrating advanced security and microsegmentation capabilities directly into their DevOps workflows. This powerful feature enhances the agility and efficiency of IT operations, allowing for seamless automation and management of security policies and user accounts. By using Elisity's API, DevOps teams can programmatically interact with Elisity's platform, enabling a more dynamic and responsive security posture that aligns with the fast-paced, automated nature of modern DevOps environments.

The introduction of API functionality not only streamlines operational tasks but also opens up new possibilities for custom integrations and advanced automation. Whether it's managing user accounts, adjusting security policies, or integrating with existing CI/CD pipelines, Elisity's API provides a flexible and secure interface for a wide range of DevOps activities. This document will guide you through the process of setting up and utilizing Elisity's API, including creating API user accounts, managing client credentials, and understanding the enhanced user management features. With these tools at your disposal, you can effectively incorporate Elisity's robust security solutions into your DevOps strategies, ensuring both efficiency and security are at the forefront of your operations.

Let's get in to how you can access these APIs.

 

Setting Up API Client

Creating an API client in the Elisity platform is a critical step for integrating its features into DevOps workflows. Here's a concise guide on how to set up an API client:

1. Creating an API Client

Go to the Settings > Admin > User Management tab

Select API Clients in the left side menu: Click on “Add API Client" in the top right.

 

2. Fill in Client Details

Role: Assign a suitable role for the API client based on the access and permissions needed. These are custom defined by your organization. It's important to note that the role permissions directly impact what API endpoints you can access using this API client. These role permissions are roughly mirrored between what is accessible in the UI and what API endpoints are accessible through the assigned role. To learn more about creating user roles, see our RBAC article.

Access Duration: This is a configurable timeout for the API Client that deactivates the API Client at the end of the expiration period. The value entered is the number of days for the Client expiration.

Set Unlimited Access: Check this box if you never want the API Client to expire.

Description: Add a brief description of the API client's intended purpose or role in your DevOps activities.

 

Generate API Credentials:

Click on “Generate Credentials.”

Securely copy and save the displayed Client ID and Client Secret.

 

3. Completing the Client Setup

Finish the Setup: After copying the credentials, click “Close” to close the setup window.

Your API client is now ready to be integrated into your DevOps processes. These credentials are crucial for authenticating with the Elisity API and should be securely managed.

 

Managing Client Credentials

Effective management of client credentials is essential for secure and efficient use of the Elisity API in DevOps operations. This section outlines the process of regenerating and managing these credentials for your API clients.

Regenerating Client Credentials

Accessing Regeneration Option:

  • Navigate to the API client in the User Management section.
  • Select the API client for which you need new credentials.

  • Click “Regenerate Client Credentials.”
  • A new Client Secret will be generated, while the Client ID remains the same.
  • Securely copy and store the new Client Secret immediately, as it is displayed only once.

Best Practices

  • Treat Client Secrets with the same level of security as passwords.
  • Store them securely using password managers or encrypted storage solutions.
  • Regularly update and rotate Client Secrets to maintain security.

Impact on Existing Integrations:

  • Be aware that regenerating credentials will require updating the Client Secret in all existing integrations where it’s used.
  • Plan regeneration and updates to minimize disruption to your DevOps processes.

By following these steps, you can ensure that your API client credentials are generated, managed, and stored securely, maintaining the integrity of your Elisity API integrations within your DevOps workflows. Proper credential management not only secures access but also streamlines your operations by avoiding unnecessary disruptions.

 

NOTE: API User Credentials have a default lifetime of 90 days. Credentials must be regenerated after the 90 day expiry. In a future release, this lifetime will be configurable. 

 

Accessing API Documentation

In our API documentation, you can find API URLs to perform various actions in Cloud Control Center. You can also find API schemas and available authorizations, including the token URL for the API server. This page also offers tools for testing API functions. Lets get into some of these functions.

Getting to the API documentation portal is pretty straightforward. Just click on the help center icon in the top left of Cloud Control Center. 
<screenshot>


Once you are in the API Documentation, there are several areas that may be useful to you.
 
 

 

1. Your available API server URL(s)

Currently there is only one API server per Cloud Control Center, so you will see the URL of your Cloud Control Center here. 

2. Authorize Button and Toke URL

Here you can find your Token URL. Your Token URL is required to use Oauth2 Client ID and Client Secret for API authorization. By default, you are authorized based on your user role permissions for your current session in Cloud Control Center. For more information on user roles and permissions, see our RBAC article. However, you can test any created API Client credentials here. Some examples of test cases might be authentication testing, testing API endpoint access for various roles, and testing jwt token authorization.

 

3. OpenID Scope for Testing API Endpoints

Some API endpoints require the inclusion of an openid scope to enable authentication. You can include this scope in your API authorizations window when entering your client credentials to test those endpoints that require this scope. 

3. API Endpoint List

The list of available API endpoint URLs and descriptions of what functions they provide are listed categorically in the documentation page.

Testing API Endpoints

Our API documentation includes an interactive interface that allows you to test API endpoints directly within the documentation. This powerful feature enables you to quickly confirm the behavior of API calls and troubleshoot any issues that may arise.

Note: If using API Client Credentials on Cloud Control Center version 15.7, scope=openid must be included in the headers for successfully retrieving an auth token. This is missing in the API Documentation Portal and will be updated in Cloud Control Center version 15.8.


 

How to Test the API

Here’s a step-by-step guide on how to use the testing feature:

  1. Selecting an Endpoint to Test:
    • Within the API documentation, navigate to the endpoint you want to test.
    • For example, if you want to search for a device by its MAC address, you'd select the GET /api/identity-graph/v1/devices endpoint.
  2. Entering Request Parameters:
    • Input the necessary parameters required by the endpoint. Fields marked with an asterisk (*) are mandatory.
    • In our example, you would enter the MAC address of the device into the mac parameter field.
  3. Executing the Request:
    • Click the "Execute" button to send the request to the API.
    • The interface will display the complete curl command used, which can be useful for debugging or for replicating the test in a terminal.
  4. Reviewing the Response:
    • The server response will be displayed below, including status codes, headers, and the body.
    • A successful call to the GET /api/identity-graph/v1/devices endpoint will return a 200 OK status and the details of the device associated with the provided MAC address. Under the server response, you can find a list of all possible server responses with example data.

Features Available for Use

  • Parameter Inputs: Easy-to-use fields for entering path parameters, query strings, and other request data. See API schemas for details.
  • Authorization Handling: Conveniently add authentication tokens or credentials, if required by the endpoint.
  • Response Viewing: Immediate display of the response, including headers, status codes, and the response body, formatted for readability.
  • Curl Command Generation: For each test, the equivalent curl command is provided, allowing for easy reproduction of the test outside the documentation environment.
  • Request URL: See the exact request URL syntax with the values that you passed.
  • Download Option: Ability to download the response content when necessary.
  • Schema and Example Value: Reference the expected response format and view example values to understand how to structure your data.

Testing Best Practices

  • Test Incrementally: Start with simple test cases to validate connectivity and authentication before moving on to more complex scenarios.
  • Check Status Codes: Use the status codes to understand the result of your API call. For example, 200 OK for success, 400 Bad Request for client-side errors, and 500 Internal Server Error for server-side issues.
  • Validate Responses: Ensure that the response structure and data match what's expected as per the API schema.
  • Record Tests: Keep records of your tests, especially if you encounter unexpected behaviors, to aid in debugging and development.

API Schemas

At the bottom of our API documentation, you'll find the API Schemas section. This is a comprehensive list of structured data models, detailing how data should be formatted when interacting with our API. Schemas are essential for understanding the data you need to send and receive when making API calls.

Each schema outlines the attributes of data objects and their types, which you will use to format your API requests and understand the responses. Required fields are marked with an asterisk (*). Here’s how you can apply this in practice:

Let's look at the RefreshDeviceRequest schema as an example:

 


This schema is for an API request to refresh device information. Here’s what you need to know:

    accountId: A unique identifier for the account.
    domain: The domain where the device is registered.
    nodeId: An identifier for the node within the domain.
    ip: The IP address of the device.
    sid: The security identifier for the device.


When constructing a request to refresh a device's information, your JSON payload should include these fields with appropriate values, like so:

{
"accountId": "12345",
"domain": "example.com",
"nodeId": "node-1",
"ip": "192.168.1.1",
"sid": "S-1-5-21-1234567890-1234567890-1234567890-1234"
}

DevOps professionals can use these schemas to automate interactions with the API, ensuring that scripts or applications are sending requests in the correct format and handling responses properly. By referencing the schemas provided in our documentation, you can confidently build robust automation tools tailored to your operational needs.

 

Practical Use Cases for Elisity's API

Elisity's API offers a wide range of functionalities that can significantly enhance DevOps operations.

Device Management

Automated Device Tracking and Management:

  • Use CRUD operations (Create, Read, Update, Delete) to manage device records.
  • Automatically update device information or delete obsolete device records.
  • Perform bulk operations for efficient handling of multiple devices.

Device Enrichment and Analysis:

  • Enrich device data on-demand for detailed analysis.
  • Export device data for external processing or reporting.

Connector Configurations

Seamless Integration with Existing Systems:

  • Create, read, update, or delete connector configurations to integrate Elisity with various external systems.

Suppression List Management

Enhanced Control Over Alerts and Notifications:

  • Manage suppression lists to fine-tune the security alerts and notifications.

Active Directory (AD) Integration

AD Synchronization and Management:

  • Resync AD nodes, manage domain controllers, and handle AD-related data.

Security Profile and Policy Management

Dynamic Security Policy Implementation:

  • Create, update, and delete security profiles and policies.
  • Adjust policy sets and views in response to changing security needs.

Bulk Policy Operations:

  • Perform bulk updates, creations, or deletions of policies for large-scale policy management.

Observability and Troubleshooting

Real-Time Monitoring and Response:

  • Utilize observability APIs for real-time monitoring of security profiles, policies, and policy groups.

Device Troubleshooting:

  • Leverage device-related APIs for detailed troubleshooting and analysis.

Example Use Case: Updating API Credentials for IdentityGraph Connectors

In this example of leveraging the Elisity API, we are going to update a specific IdentityGraph Connector API token via API calls. 

Requirements:

  • Elisity API Access
  • Connector id attribute value
  • Connector name attribute value
  • PUT Payload

1. If you don't know the connector ID or name attribute to call upon in the PUT payload, leverage the following GET API call to return a list of configured connectors and their attributes.

Request URL

/api/identity-graph/v1/conf/all

 

Response Body

[
  {
    "id": "d8ab8f33-9076-4f74-a42f-55455220ffcb",
    "type": "MEDIGATE",
    "connectorName": "Medigate",
    "enabled": true,
    "modifiedAt": "2024-03-26T09:50:12.396600Z",
    "createdAt": "2024-03-26T09:50:12.396600Z",
    "modifiedBy": "service-account-ccc-api-client",
    "createdBy": "service-account-ccc-api-client",
    "settings": {
      "apiUrl": "https://api.medigate.io",
      "apiToken": "$Exists$",
      "repeatInterval": null
    }
  },
  {
    "id": "2ccfc50f-f29d-4098-9138-4a0383c83ade",
    "type": "SERVICE_NOW",
    "connectorName": "ServiceNow",
    "enabled": true,
    "modifiedAt": "2024-03-26T09:50:13.353814Z",
    "createdAt": "2024-03-26T09:50:13.353814Z",
    "modifiedBy": "service-account-ccc-api-client",
    "createdBy": "service-account-ccc-api-client",
    "settings": {
      "apiHost": "https://devs5.service-now.com",
      "useApiKey": false,
      "apiAuthenticationName": "admin",
      "apiSecret": "$Exists$",
      "singleDeviceQueryLimit": 50,
      "repeatInterval": null
    }
  },
  {
    "id": "f9a0aa2b-5a82-418a-9136-acee577e4150",
    "type": "CLAROTY_XDOME",
    "connectorName": "XDome",
    "enabled": true,
    "modifiedAt": "2024-03-26T09:50:14.222549Z",
    "createdAt": "2024-03-26T09:50:14.222549Z",
    "modifiedBy": "service-account-ccc-api-client",
    "createdBy": "service-account-ccc-api-client",
    "settings": {
      "apiUrl": "https://api.claroty.com",
      "apiToken": "$Exists$",
      "repeatInterval": null
    }
  },
  {
    "id": "bd68f390-6518-4471-9bf5-0c43d56e7feb",
    "type": "PALO_ALTO",
    "connectorName": "Palo Alto IoT Security",
    "enabled": true,
    "modifiedAt": "2024-03-26T09:50:15.512006Z",
    "createdAt": "2024-03-26T09:50:15.512006Z",
    "modifiedBy": "service-account-ccc-api-client",
    "createdBy": "service-account-ccc-api-client",
    "settings": {
      "apiPath": "https://banff-enterprise-demo.iot.paloaltonetworks.com/",
      "customerId": "banff-enterprise-demo",
      "keyId": "$Exists$",
      "accessKey": "$Exists$",
      "repeatInterval": null
    }
  },
  {
    "id": "0b92624b-310d-4323-8f96-96247815005c",
    "type": "CROWDSTRIKE",
    "connectorName": "CrowdStrike",
    "enabled": true,
    "modifiedAt": "2024-03-26T09:50:16.266384Z",
    "createdAt": "2024-03-26T09:50:16.266384Z",
    "modifiedBy": "service-account-ccc-api-client",
    "createdBy": "service-account-ccc-api-client",
    "settings": {
      "apiUrl": "https://api.us-231.crowdstrike.com",
      "clientId": "$Exists$",
      "clientSecret": "$Exists$",
      "repeatInterval": null
    }
  },
  {
    "id": "a6bb68d5-97cf-400c-a37a-c750b6d37f68",
    "type": "CROWDSTRIKE_ZTNA",
    "connectorName": "CrowdStrike",
    "enabled": true,
    "modifiedAt": "2024-03-26T09:50:16.846371Z",
    "createdAt": "2024-03-26T09:50:16.846371Z",
    "modifiedBy": "service-account-ccc-api-client",
    "createdBy": "service-account-ccc-api-client",
    "settings": {
      "apiUrl": "https://api.us-231.crowdstrike.com",
      "clientId": "$Exists$",
      "clientSecret": "$Exists$",
      "repeatInterval": null
    }
  }
]

 

2. Copy the attribute values for the id and ConnectorName. Append the Connector id value to the URI, add the ConnectorName and update the API Token in the request body.

Request URL

api/identity-graph/v1/conf/f9a0aa2b-5a82-418a-9136-acee577e4150

 

Request Body

{
"connectorName":"xdome",
"enabled":true,
"settings":{
"apiUrl":"https://api.claroty.com",
"apiToken":"test"
}
}

 

3. If executed correctly, you will receive a "code 204 successfully updated connector configuration" response. 

 

Support

For any issues or questions regarding the API, Elisity's support team is available to assist. We provide comprehensive support to ensure you can maximize the benefits of API integration in your DevOps processes. Reach out to support@elisity.com or your Elisity engineer to request assistance/

 

 

Was this article helpful?
0 out of 0 found this helpful