Chat now with support
Chat with Support

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

Introduction Using the SPS REST API Basic settings User management and access control Managing SPS General connection settings HTTP connections Citrix ICA connections MSSQL connections RDP connections SSH connections Telnet connections VNC connections Search, retrieve, download, and index sessions Reporting Health and maintenance Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST REST API examples

Audit policies

Querying audit policies

Querying audit policies request 

curl --cookie cookies.txt --request GET https://<IP-address-of-SPS>/api/configuration/policies/audit_policies

Querying audit policies response 

{
  "items": [
    {
      "body": {
        "encryption": {
          "enabled": false
        },
        "name": "default",
        "signing": {
          "enabled": false
        },
        "signing_and_timestamping_interval": 30,
        "timestamping": {
          "enabled": false
        }
      },
      "key": "78101850949e47437dd91d",
      "meta": {
        "href": "/api/configuration/policies/audit_policies/78101850949e47437dd91d"
      }
    },
    {
      "body": {
        "encryption": {
          "enabled": false
        },
        "name": "remote-timestamping",
        "signing": {
          "enabled": false
        },
        "signing_and_timestamping_interval": 42,
        "timestamping": {
          "enabled": true,
          "server": {
            "oid": {
              "enabled": true,
              "policy_oid": "2.3.5.3.1.5.32.322.32"
            },
            "selection": "remote",
            "server_url": "http://tsa.example.com/"
          }
        }
      },
      "key": "4110330695c094b5776670",
      "meta": {
        "href": "/api/configuration/policies/audit_policies/4110330695c094b5776670"
      }
    }
  ],
  "meta": {
      "first": "/api/configuration/policies/aa_plugin_instances",
      "href": "/api/configuration/policies/audit_policies",
      "last": "/api/configuration/policies/usermapping_policies",
      "next": "/api/configuration/policies/backup_policies",
      "parent": "/api/configuration/policies",
      "previous": "/api/configuration/policies/archive_cleanup_policies",
      "transaction": "/api/transaction"
  }
}
Querying the default audit policy

Querying the default audit policy request 

curl --cookie cookies.txt --request GET https://<IP-address-of-SPS>/api/configuration/policies/audit_policies/78101850949e47437dd91d

Querying the default audit policy response 

{
  "key": "78101850949e47437dd91d",
  "body":
    {
      "name": "default",
      "timestamping": {
        "enabled": false
      },
      "encryption": {
        "enabled": false
      },
      "signing": {
        "enabled": false
      },
      "signing_and_timestamping_interval": 30
    },
    "meta": {
        "first": "/api/configuration/policies/audit_policies/78101850949e47437dd91d",
        "href": "/api/configuration/policies/audit_policies/78101850949e47437dd91d",
        "last": "/api/configuration/policies/audit_policies/4110330695c094b5776670",
        "next": "/api/configuration/policies/audit_policies/4110330695c094b5776670",
        "parent": "/api/configuration/policies/audit_policies",
        "previous": null,
        "transaction": "/api/transaction"
    }
}
Querying a specific audit policy

Querying a specific audit policy request 

curl --cookie cookies.txt --request GET https://<IP-address-of-SPS>/api/configuration/policies/audit_policies/4110330695c094b5776670

Querying a specific audit policy response 

{
  "body": {
    "encryption": {
      "enabled": false
    },
    "name": "remote-timestamping",
    "signing": {
      "enabled": false
    },
    "signing_and_timestamping_interval": 42,
    "timestamping": {
      "enabled": true,
      "server": {
        "oid": {
          "enabled": true,
          "policy_oid": "2.3.5.3.1.5.32.322.32"
        },
        "selection": "remote",
        "server_url": "http://tsa.example.com/"
      }
    }
  },
  "key": "4110330695c094b5776670",
  "meta": {
    "first": "/api/configuration/policies/audit_policies/78101850949e47437dd91d",
    "href": "/api/configuration/policies/audit_policies/4110330695c094b5776670",
    "last": "/api/configuration/policies/audit_policies/4110330695c094b5776670",
    "next": null,
    "parent": "/api/configuration/policies/audit_policies",
    "previous": "/api/configuration/policies/audit_policies/78101850949e47437dd91d",
    "transaction": "/api/transaction"
  }
}
Configure only upstream encription

Configure only upstream encription request 

curl --cookie cookies.txt --request POST --data '@-' https://<IP-address-of-SPS>/api/configuration/policies/audit_policies <<'REQUEST'
{
    "name": "upstream_only",
    "timestamping": {
      "enabled": false
    },
    "encryption": {
      "enabled": true,
      "certificates": [],
      "different_certificates_for_upstream": {
        "enabled": true,
        "certificates": [
          {
            "certificate": {
              "pem": "-----BEGIN CERTIFICATE-----\nMIIEgjCCA2qgAwIBAgIBITANBgkqhkiG9w0BAQsFADCBzDELMAkGA1UEBhMCUk8x\nFTATBgNVBAgMDFRoZVJvb3RTdGF0ZTEYMBYGA1UEBwwPVGhlUm9vdExvY2FsaXR5\nMRwwGgYDVQQKDBNUaGVSb290T3JnYW5pemF0aW9uMSIwIAYDVQQLDBlUaGVSb290\nT3JnYW5pemF0aW9uYWxVbml0MSAwHgYDVQQDDBd0aGUucm9vdC5jb21tb24ubmFt\nZS5pbzEoMCYGCSqGSIb3DQEJARYZdGhlQHJvb3QuZW1haWwuYWRkcmVzcy5pbzAe\nFw0xNDA4MjUxMjQ0MjFaFw0yNDA4MjIxMjQ0MjFaMIHMMQswCQYDVQQGEwJDUjEV\nMBMGA1UECAwMVGhlQ2VydFN0YXRlMRgwFgYDVQQHDA9UaGVDZXJ0TG9jYWxpdHkx\nHDAaBgNVBAoME1RoZUNlcnRPcmdhbml6YXRpb24xIjAgBgNVBAsMGVRoZUNlcnRP\ncmdhbml6YXRpb25hbFVuaXQxIDAeBgNVBAMMF3RoZS5jZXJ0LmNvbW1vbi5uYW1l\nLmlvMSgwJgYJKoZIhvcNAQkBFhl0aGVAY2VydC5lbWFpbC5hZGRyZXNzLmlvMIIB\nIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA/JERC+o1UksvUfbzS5Yp77CN\nlS6RkkdZLPjl2i9+ACzv/lOy4Kn6qLMRPEj/evRKNiu8vdMLPANN1rYG8IioxetE\nhKj3OVyj5YBJ1BJqJiUrCbkGQCNX2zlfD/VsPDKvtMmcM6F/PEUwl577uQcXhquz\nKeJpSgDbwcANcUNm30YkpT9MTEjfYPdPaLb9jh8+7K3c29ZsJzIRSY3jRISqvK/L\nYNs07oDXfEpeZBNliqTvqhii/0ohnUdKVkXnusLCBb2lyaiOY2nhMz4U2023gJBZ\n3q9ny8dpH3y4RxuygqlhqEaxsDTfMeuWDTkKIxaWHgat/+yeSssXUHx4bu1jTwID\nAQABo20wazAJBgNVHRMEAjAAMBEGCWCGSAGG+EIBAQQEAwIGQDALBgNVHQ8EBAMC\nBeAwHQYDVR0OBBYEFPMG1JzFCtuh8ry7ru5C2IMFPmCLMB8GA1UdIwQYMBaAFBwk\ntYLmRkTRzUryEUQobduVjiThMA0GCSqGSIb3DQEBCwUAA4IBAQAomh6B7H4WsGDL\nzyduEVX6otMhu82j7oeK2WuYaHczHPPzQc0pVTl7TOMMuQR3xNeohuUx7mFjx6MO\n11ksdN4lzo9r94GjYrO9WvRTsQDMJxsrVry49MKjh4Gg21IAuKxvdU9MMUhuhblQ\ntxSpikxMpynf1JK3C+A57M3yAhCCPLjDX1iWXuyGIW28J0FEdTTNAinBRyy18wFG\n/vfOVn1sKpAp5nT8CWWHt3KNOVPsUh41GulBzMFEXSTSggzD/B1dNBfC752k0AGy\nOVHLqWAqnoM6Go9bhkrRWGhH0YIHZFtEeIuNsPYnULNS5yOS3a0FMOpHBQ8kfz9R\nGwrzti7q\n-----END CERTIFICATE-----\n"
            },
            "four_eyes_certificate": null
          }
        ]
      }
    },
    "signing": {
      "enabled": false
    },
    "signing_and_timestamping_interval": 30
}
REQUEST
Configure signing without traffic encryption

Configure signing without traffic encryption request 

curl --cookie cookies.txt --request POST --data '@-' https://<IP-address-of-SPS>/api/configuration/policies/audit_policies <<'REQUEST'
{
    "name": "sign_no_traffic_encryption",
    "timestamping": {
      "enabled": false
    },
    "encryption": {
      "enabled": false
    },
    "signing": {
      "enabled": true,
      "x509_identity": "x509-identity-0"
    },
    "signing_and_timestamping_interval": 30
}
REQUEST
Configure signing, and traffic encryption with a single certificate

Configure signing, and traffic encryption with a single certificate request 

curl --cookie cookies.txt --request POST --data '@-' https://<IP-address-of-SPS>/api/configuration/policies/audit_policies <<'REQUEST'
{
    "name": "sign_with_traffic_encryption",
    "timestamping": {
      "enabled": false
    },
    "encryption": {
      "enabled": true,
      "certificates": [
          {
            "certificate": {
              "pem": "-----BEGIN CERTIFICATE-----\nMIIEgjCCA2qgAwIBAgIBITANBgkqhkiG9w0BAQsFADCBzDELMAkGA1UEBhMCUk8x\nFTATBgNVBAgMDFRoZVJvb3RTdGF0ZTEYMBYGA1UEBwwPVGhlUm9vdExvY2FsaXR5\nMRwwGgYDVQQKDBNUaGVSb290T3JnYW5pemF0aW9uMSIwIAYDVQQLDBlUaGVSb290\nT3JnYW5pemF0aW9uYWxVbml0MSAwHgYDVQQDDBd0aGUucm9vdC5jb21tb24ubmFt\nZS5pbzEoMCYGCSqGSIb3DQEJARYZdGhlQHJvb3QuZW1haWwuYWRkcmVzcy5pbzAe\nFw0xNDA4MjUxMjQ0MjFaFw0yNDA4MjIxMjQ0MjFaMIHMMQswCQYDVQQGEwJDUjEV\nMBMGA1UECAwMVGhlQ2VydFN0YXRlMRgwFgYDVQQHDA9UaGVDZXJ0TG9jYWxpdHkx\nHDAaBgNVBAoME1RoZUNlcnRPcmdhbml6YXRpb24xIjAgBgNVBAsMGVRoZUNlcnRP\ncmdhbml6YXRpb25hbFVuaXQxIDAeBgNVBAMMF3RoZS5jZXJ0LmNvbW1vbi5uYW1l\nLmlvMSgwJgYJKoZIhvcNAQkBFhl0aGVAY2VydC5lbWFpbC5hZGRyZXNzLmlvMIIB\nIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA/JERC+o1UksvUfbzS5Yp77CN\nlS6RkkdZLPjl2i9+ACzv/lOy4Kn6qLMRPEj/evRKNiu8vdMLPANN1rYG8IioxetE\nhKj3OVyj5YBJ1BJqJiUrCbkGQCNX2zlfD/VsPDKvtMmcM6F/PEUwl577uQcXhquz\nKeJpSgDbwcANcUNm30YkpT9MTEjfYPdPaLb9jh8+7K3c29ZsJzIRSY3jRISqvK/L\nYNs07oDXfEpeZBNliqTvqhii/0ohnUdKVkXnusLCBb2lyaiOY2nhMz4U2023gJBZ\n3q9ny8dpH3y4RxuygqlhqEaxsDTfMeuWDTkKIxaWHgat/+yeSssXUHx4bu1jTwID\nAQABo20wazAJBgNVHRMEAjAAMBEGCWCGSAGG+EIBAQQEAwIGQDALBgNVHQ8EBAMC\nBeAwHQYDVR0OBBYEFPMG1JzFCtuh8ry7ru5C2IMFPmCLMB8GA1UdIwQYMBaAFBwk\ntYLmRkTRzUryEUQobduVjiThMA0GCSqGSIb3DQEBCwUAA4IBAQAomh6B7H4WsGDL\nzyduEVX6otMhu82j7oeK2WuYaHczHPPzQc0pVTl7TOMMuQR3xNeohuUx7mFjx6MO\n11ksdN4lzo9r94GjYrO9WvRTsQDMJxsrVry49MKjh4Gg21IAuKxvdU9MMUhuhblQ\ntxSpikxMpynf1JK3C+A57M3yAhCCPLjDX1iWXuyGIW28J0FEdTTNAinBRyy18wFG\n/vfOVn1sKpAp5nT8CWWHt3KNOVPsUh41GulBzMFEXSTSggzD/B1dNBfC752k0AGy\nOVHLqWAqnoM6Go9bhkrRWGhH0YIHZFtEeIuNsPYnULNS5yOS3a0FMOpHBQ8kfz9R\nGwrzti7q\n-----END CERTIFICATE-----\n"
            },
            "four_eyes_certificate": null
          }
      ],
      "different_certificates_for_upstream": {
        "enabled": false
      }
    },
    "signing": {
      "enabled": true,
      "x509_identity": "x509-identity-0"
    },
    "signing_and_timestamping_interval": 30
}
REQUEST
Configure without timestamping

Configure without timestamping request 

curl --cookie cookies.txt --request POST --data '@-' https://<IP-address-of-SPS>/api/configuration/policies/audit_policies <<'REQUEST'
{
    "name": "timestamping_disabled",
    "timestamping": {
      "enabled": false
    },
    "encryption": {
      "enabled": false
    },
    "signing": {
      "enabled": false
    },
    "signing_and_timestamping_interval": 30
}
REQUEST
Configure local timestamping

Configure local timestamping request 

curl --cookie cookies.txt --request POST --data '@-' https://<IP-address-of-SPS>/api/configuration/policies/audit_policies <<'REQUEST'
{
    "name": "local_timestamping",
    "timestamping": {
      "enabled": true,
      "server": {
        "selection": "local"
      }
    },
    "encryption": {
      "enabled": false
    },
    "signing": {
      "enabled": false
    },
    "signing_and_timestamping_interval": 30
}
REQUEST
Configure external timestamping

Configure external timestamping request 

curl --cookie cookies.txt --request POST --data '@-' https://<IP-address-of-SPS>/api/configuration/policies/audit_policies <<'REQUEST'
{
    "name": "external_timestamping",
    "timestamping": {
      "enabled": true,
      "server": {
        "selection": "remote",
        "server_url": "http://tsa.example.com/",
        "oid": {
          "enabled": true,
          "policy_oid": "2.3.5.3.1.5.32.322.32"
        }
      }
    },
    "encryption": {
      "enabled": false
    },
    "signing": {
      "enabled": false
    },
    "signing_and_timestamping_interval": 30
}
REQUEST

Audited users

Querying audited users

Querying audited users request 

curl --cookie cookies.txt --request GET https://<IP-address-of-SPS>/api/audit/users

Querying audited users response 

{
  "items": [
    {
      "has_valid_score": false,
      "id": "userName4",
      "last_seen": "2023-06-21T15:31:40.000Z",
      "score": null,
      "score_timestamp": "2023-06-22T03:31:40.000Z"
    },
    {
      "has_valid_score": true,
      "id": "userName1",
      "last_seen": "2023-06-08T07:20:09.000Z",
      "score": 1,
      "score_timestamp": "2023-06-06T03:23:25.000Z"
    },
    {
      "has_valid_score": true,
      "id": "userName3",
      "last_seen": "2023-05-06T12:50:05.000Z",
      "score": 2,
      "score_timestamp": "2023-05-05T23:15:45.000Z"
    },
    {
      "has_valid_score": false,
      "id": "userName2",
      "last_seen": "2023-05-06T03:23:25.000Z",
      "score": 3,
      "score_timestamp": "2023-05-05T09:22:25.000Z"
    }
  ],
  "meta": {
    "href": "/api/audit/users",
    "limit": 100,
    "parent": "/api/audit"
  }
}
Querying audited users using the `limit` parameter to limit the search results

Querying audited users using the `limit` parameter to limit the search results request 

curl --cookie cookies.txt --request GET https://<IP-address-of-SPS>/api/audit/users?limit=1

Querying audited users using the `limit` parameter to limit the search results response 

{
  "items": [
    {
      "has_valid_score": false,
      "id": "userName4",
      "last_seen": "2023-06-21T15:31:40.000Z",
      "score": null,
      "score_timestamp": "2023-06-22T03:31:40.000Z"
    }
  ],
  "meta": {
    "href": "/api/audit/users",
    "limit": 1,
    "parent": "/api/audit"
  }
}
Querying audited users using the `sort` parameter to sort the search results

Querying audited users using the `sort` parameter to sort the search results request 

curl --cookie cookies.txt --request GET https://<IP-address-of-SPS>/api/audit/users?sort=score

Querying audited users using the `sort` parameter to sort the search results response 

{
  "items": [
    {
      "has_valid_score": false,
      "id": "userName4",
      "last_seen": "2023-06-21T15:31:40.000Z",
      "score": null,
      "score_timestamp": "2023-06-22T03:31:40.000Z"
    },
    {
      "has_valid_score": true,
      "id": "userName1",
      "last_seen": "2023-06-08T07:20:09.000Z",
      "score": 1,
      "score_timestamp": "2023-06-06T03:23:25.000Z"
    },
    {
      "has_valid_score": true,
      "id": "userName3",
      "last_seen": "2023-05-06T12:50:05.000Z",
      "score": 2,
      "score_timestamp": "2023-05-05T23:15:45.000Z"
    },
    {
      "has_valid_score": false,
      "id": "userName2",
      "last_seen": "2023-05-06T03:23:25.000Z",
      "score": 3,
      "score_timestamp": "2023-05-05T09:22:25.000Z"
    }
  ],
  "meta": {
    "href": "/api/audit/users",
    "limit": 100,
    "parent": "/api/audit"
  }
}
Querying audited users using the `has_valid_score` parameter to filter the search results

Querying audited users using the `has_valid_score` parameter to filter the search results request 

curl --cookie cookies.txt --request GET https://<IP-address-of-SPS>/api/audit/users?has_valid_score=true

Querying audited users using the `has_valid_score` parameter to filter the search results response 

{
  "items": [
    {
      "has_valid_score": true,
      "id": "userName1",
      "last_seen": "2023-06-08T07:20:09.000Z",
      "score": 1,
      "score_timestamp": "2023-06-06T03:23:25.000Z"
    },
    {
      "has_valid_score": true,
      "id": "userName3",
      "last_seen": "2023-05-06T12:50:05.000Z",
      "score": 2,
      "score_timestamp": "2023-05-05T23:15:45.000Z"
    }
  ],
  "meta": {
    "href": "/api/audit/users",
    "limit": 100,
    "parent": "/api/audit"
  }
}

Configuration default values

Querying the default values for singleton resources, for example syslog servers

Querying the default values for singleton resources, for example syslog servers request 

curl --cookie cookies.txt --request PUT --data '@-' https://<IP-address-of-SPS>/api/configuration/management/syslog?defaults <<'REQUEST'
{
    "receivers": [
        {}
    ]
}
REQUEST

Querying the default values for singleton resources, for example syslog servers response 

{
    "body": {
        "encryption": {
            "client_authentication": null,
            "trust_store": null
        },
        "include_node_id": true,
        "receivers": [
            {
                "address": {
                    "selection": "ip",
                    "value": "127.0.0.1"
                },
                "port": 514,
                "protocol": {
                    "ip_protocol": "tcp",
                    "protocol_type": "legacy-bsd",
                    "tls_enabled": false
                }
            }
        ]
    },
    "key": "syslog",
    "meta": {
        "first": "/api/configuration/management/accounting",
        "href": "/api/configuration/management/syslog",
        "last": "/api/configuration/management/web_gateway_authentication",
        "next": "/api/configuration/management/system_backup",
        "parent": "/api/configuration/management",
        "previous": "/api/configuration/management/support_info",
        "transaction": "/api/transaction"
    }
}
Querying defaults for objects in a container, for example SSH authentication policies

Querying defaults for objects in a container, for example SSH authentication policies request 

curl --cookie cookies.txt --request POST --data '@-' https://<IP-address-of-SPS>/api/configuration/ssh/authentication_policies?defaults <<'REQUEST'
{
    "backend": {
        "selection": "radius"
    }
}
REQUEST

Querying defaults for objects in a container, for example SSH authentication policies response 

{
    "body": {
        "backend": {
            "authentication_protocol": "pap",
            "selection": "radius",
            "servers": [
                {
                    "address": {
                        "selection": "ip",
                        "value": "127.0.0.1"
                    },
                    "port": 1812,
                    "shared_secret": {
                        "key": "",
                        "meta": {
                            "href": "/api/configuration/passwords"
                        }
                    }
                }
            ]
        },
        "gateway_methods": {
            "kerberos": false,
            "password": false,
            "public_key": false
        },
        "name": "unnamed-ssh-authentication-policy",
        "relayed_methods": {
            "kerberos": false,
            "keyboard_interactive": true,
            "password": true,
            "public_key": {
                "selection": "agent"
            }
        }
    },
    "key": "",
    "meta": {
        "first": "/api/configuration/ssh/authentication_policies",
        "href": "/api/configuration/ssh/authentication_policies",
        "last": "/api/configuration/ssh/settings_policies",
        "next": "/api/configuration/ssh/channel_policies",
        "parent": "/api/configuration/ssh",
        "previous": null,
        "transaction": "/api/transaction"
    }
}

Date and time configuration

Querying date and time configuration

Querying date and time configuration request 

curl --cookie cookies.txt --request GET https://<IP-address-of-SPS>/api/configuration/datetime

Querying date and time configuration response 

{
    "items": [
        {
            "key": "ntp_servers",
            "meta": { "href": "/api/configuration/datetime/ntp_servers" }
        },
        {
            "key": "timezone",
            "meta": { "href": "/api/configuration/datetime/timezone" }
        }
    ],
    "meta": {
        "first": "/api/configuration/aaa",
        "href": "/api/configuration/datetime",
        "last": "/api/configuration/x509",
        "next": "/api/configuration/http",
        "parent": "/api/configuration",
        "previous": "/api/configuration/alerting",
        "transaction": "/api/transaction"
    }
}
Querying timezone configuration

Querying timezone configuration request 

curl --cookie cookies.txt --request GET https://<IP-address-of-SPS>/api/configuration/datetime/timezone

Querying timezone configuration response 

{
    "key": "timezone",
    "body": "America/New_York",
    "meta": {
        "first": "/api/configuration/datetime/ntp_servers",
        "href": "/api/configuration/datetime/timezone",
        "last": "/api/configuration/datetime/timezone",
        "next": null,
        "parent": "/api/configuration/datetime",
        "previous": "/api/configuration/datetime/ntp_servers",
        "transaction": "/api/transaction"
    }
}
Querying NTP servers configuration

Querying NTP servers configuration request 

curl --cookie cookies.txt --request GET https://<IP-address-of-SPS>/api/configuration/datetime/ntp_servers

Querying NTP servers configuration response 

{
    "key": "ntp_servers",
    "body": [
        {
            "selection": "fqdn",
            "value": "pool.ntp.org"
        }
    ],
    "meta": {
        "first": "/api/configuration/datetime/ntp_servers",
        "href": "/api/configuration/datetime/ntp_servers",
        "last": "/api/configuration/datetime/timezone",
        "next": "/api/configuration/datetime/timezone",
        "parent": "/api/configuration/datetime",
        "previous": null,
        "transaction": "/api/transaction"
    }
}
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating