One Identity Safeguard for Privileged Sessions 6.0.4 - REST API Reference Guide

Custom subchapters

List of the reporting subchapters created from custom queries to the SPS connection database. The list of tables and fields you can query are described in "Database tables available for custom queries" in the Administration Guide.

URL

GET https://<IP-address-of-SPS>/api/configuration/reporting/custom_subchapters

Cookies

Sample request

The following command lists the available custom subchapters.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/reporting/custom_subchapters

The following command retrieves the properties of a specific subchapter.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/reporting/custom_subchapters/<object-id>

Response

The following is a sample response received when listing custom subchapters.

For details of the meta object, see Message format.

{
  "meta": {
    "first": "/api/configuration/reporting/content_subchapters",
    "href": "/api/configuration/reporting/custom_subchapters",
    "last": "/api/configuration/reporting/statistics_subchapters",
    "next": "/api/configuration/reporting/predefined_reports",
    "parent": "/api/configuration/reporting",
    "previous": "/api/configuration/reporting/content_subchapters",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "5983143445707eb740fee3",
      "meta": {
        "href": "/api/configuration/reporting/custom_subchapters/5983143445707eb740fee3"
      }
    }
  ]
}

When retrieving the endpoint of a specific subchapter, the response is the following.

{
  "body": {
    "access": [
      "search"
    ],
    "chart": {
      "column_titles": [
        "col1",
        "col2"
      ],
      "type": "list"
    },
    "name": "API_test_adv_stats",
    "query": "select\n  to_timestamp(audit_trail_downloads.download_time),\n  audit_trail_downloads.username,\n  channels.channel_type,\n  channels.connection,\n  audit_trail_downloads.ip\nfrom audit_trail_downloads,\n     channels\nwhere channels._connection_channel_id = audit_trail_downloads.id\nand audit_trail_downloads.download_time <= :range_start\nand audit_trail_downloads.download_time > :range_end\nand audit_trail_downloads.username != 'admin'\norder by audit_trail_downloads.download_time;"
  },
  "key": "5983143445707eb740fee3",
  "meta": {
    "first": "/api/configuration/reporting/custom_subchapters/5983143445707eb740fee3",
    "href": "/api/configuration/reporting/custom_subchapters/5983143445707eb740fee3",
    "last": "/api/configuration/reporting/custom_subchapters/5983143445707eb740fee3",
    "next": null,
    "parent": "/api/configuration/reporting/custom_subchapters",
    "previous": null,
    "transaction": "/api/transaction"
  }
}

Examples:

Create a bar chart with a custom title for the y-axis:

"chart": {
  "type": "bar",
  "y_axis_title": "Y_axis"
}

Create a pie chart:

"chart": {
  "type": "pie"
}

Create a list with custom column names:

"chart": {
  "column_titles": [
    "col1",
    "col2"
  ],
  "type": "list"
}

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.

Add a custom subchapter

To add a custom subchapter, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Create the JSON object for the new subchapter.

   POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/reporting/custom_subchapters endpoint. You can find a detailed description of the available parameters listed in Element .

   If the POST request is successful, the response includes the key of the new subchapter. For example:

   {
     "key": "9a8f7f19-edbf-4327-9d3a-9f527e7331ee",
     "meta": {
       "href": "/api/configuration/reporting/custom_subchapters/9a8f7f19-edbf-4327-9d3a-9f527e7331ee",
       "parent": "/api/configuration/reporting/custom_subchapters",
       "transaction": "/api/transaction"
     }
   }

3. Commit your changes.

   For details, see Commit a transaction.

Modify a custom subchapter

To modify a subchapter, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the subchapter.

   PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/reporting/custom_subchapters/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in Element .

3. Commit your changes.

   For details, see Commit a transaction.

Connection statistics subchapters

List of the reporting subchapters created from connection statistics.

URL

GET https://<IP-address-of-SPS>/api/configuration/reporting/statistics_subchapters

Cookies

Sample request

The following command lists the available subchapters.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/reporting/statistics_subchapters

The following command retrieves the properties of a specific subchapter.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/reporting/statistics_subchapters/<subchapter-id>

Response

The following is a sample response received when listing connection statistics subchapters.

For details of the meta object, see Message format.

{
  "meta": {
    "first": "/api/configuration/reporting/content_subchapters",
    "href": "/api/configuration/reporting/statistics_subchapters",
    "last": "/api/configuration/reporting/statistics_subchapters",
    "next": null,
    "parent": "/api/configuration/reporting",
    "previous": "/api/configuration/reporting/reports",
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "21111736175707f1df8bea1",
      "meta": {
        "href": "/api/configuration/reporting/statistics_subchapters/21111736175707f1df8bea1"
      }
    }
  ]
}

When retrieving the endpoint of a specific subchapter, the response is the following.

{
  "body": {
    "access": [
      "search",
      "reporting"
    ],
    "chart": {
      "type": "list"
    },
    "name": "stats_simple",
    "query": {
      "column": "username",
      "filter": [
        {
          "column": "protocol",
          "is_exact": false,
          "is_inverted": false,
          "value": "ssh"
        },
        {
          "column": "username",
          "is_exact": false,
          "is_inverted": false,
          "value": "admin"
        }
      ],
      "limit": 15,
      "order": "top"
    }
  },
  "key": "496444806570e9c7e32c30",
  "meta": {
    "first": "/api/configuration/reporting/statistics_subchapters/21111736175707f1df8bea1",
    "href": "/api/configuration/reporting/statistics_subchapters/496444806570e9c7e32c30",
    "last": "/api/configuration/reporting/statistics_subchapters/496444806570e9c7e32c30",
    "next": null,
    "parent": "/api/configuration/reporting/statistics_subchapters",
    "previous": "/api/configuration/reporting/statistics_subchapters/1539306268570e9442cab6c",
    "transaction": "/api/transaction"
  }
}

Examples:

Create statistics about the 15 most common usernames used in SSH connections.

• Create a bar chart.

  {
    "access": [
      "reporting",
      "search"
    ],
    "chart": {
      "type": "bar"
    },
    "name": "stats_bar",
    "query": {
      "column": "username",
      "filter": [
        {
          "column": "protocol",
          "is_exact": false,
          "is_inverted": false,
          "value": "ssh"
        }
      ],
      "limit": 15,
      "order": "top"
    }
  }

• Create a pie chart.

  {
    "access": [
      "reporting",
      "search"
    ],
    "chart": {
      "type": "pie"
    },
    "name": "stats_pie",
    "query": {
      "column": "username",
      "filter": [
        {
          "column": "protocol",
          "is_exact": false,
          "is_inverted": false,
          "value": "ssh"
        }
      ],
      "limit": 15,
      "order": "top"
    }
  }

• Create a list.

  {
      "access": [
        "reporting",
        "search"
      ],
      "chart": {
        "type": "list"
      },
      "name": "stats_list",
      "query": {
        "column": "username",
        "filter": [
          {
            "column": "protocol",
            "is_exact": false,
            "is_inverted": false,
            "value": "ssh"
          }
        ],
        "limit": 15,
        "order": "top"
      }
    }

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.

Add a connection statistics subchapter

To add a connection statistics subchapter, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Create the JSON object for the new subchapter.

   POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/reporting/statistics_subchapters/ endpoint. You can find a detailed description of the available parameters listed in Element .

   If the POST request is successful, the response includes the key of the new subchapter. For example:

   {
     "key": "769e627d-515d-4d26-a03e-cb2ed0bbee04",
     "meta": {
       "href": "/api/configuration/reporting/statistics_subchapters/769e627d-515d-4d26-a03e-cb2ed0bbee04",
       "parent": "/api/configuration/reporting/statistics_subchapters",
       "transaction": "/api/transaction"
     }
   }

3. Commit your changes.

   For details, see Commit a transaction.

Modify a connection statistics subchapter

To modify a subchapter, you have to:

1. Open a transaction.

   For details, see Open a transaction.

2. Modify the JSON object of the subchapter.

   PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/reporting/statistics_subchapters//<key-of-the-subchapter> endpoint. You can find a detailed description of the available parameters listed in Element .

3. Commit your changes.

   For details, see Commit a transaction.

Health and maintenance

Topics:

Monitor appliance health status

To monitor the health status of an appliance, complete the following steps.

1. Query the /api/health-status endpoint.

   curl --cookie cookies https://<IP-address-of-SPS>/api/health-status

   The following is a sample response received.

   For details of the meta object, see Message format.

   For details of the other objects, see tables Cluster status details and "issues" object details.

   {
       "health_status": {
           "memory": 62.5,
           "disk": 1.9,
           "swap": 0,
           "load1": 0.53,
           "load5": 0.68,
           "load15": 0.37,
           "sessions": {
               "ssh": 3,
               "rdp": 4
           },
           "total_sessions": 7
       }
   }

   Elements		Type	Description
   health_status		null or object	The health status of a node. If the node is down, the value is null. Otherwise, the health-related data is listed.
   	memory	floating point integer (percent)	Memory use
   	disk	floating point integer (percent)	Hard disk use
   	swap	floating point integer (percent)	Swap use
   	load1	floating point integer	The average system load during the last one minute. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
   	load5	floating point integer	The average system load during the last five-minute period. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
   	load15	floating point integer	The average system load during the last fifteen-minute period. The values mean the following: < 1: low system load 1-5: high system load > 5: extremely high system load
   	sessions	string	The protocol type and the number of ongoing sessions. For example: "sessions": { "ssh": 3, "rdp": 4 },
   	total_sessions	integer (number of)	The total number of ongoing sessions.