Chat now with support

Get Live Help
Complete Registration

Sign In

Request Pricing

Contact Sales

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

Message format How to configure SPS using REST How to configure SPS using REST: a sample transaction

Authenticate to the SPS REST API Authenticate to the SPS REST API using X.509 certificate Listing SPS login methods Retrieve user information Checking the transaction status Open a transaction Commit a transaction Delete a transaction Reviewing the changelog of a transaction Defaults query parameter Application level error codes Navigating the configuration of SPS Modifying the configuration of SPS

Delete an object Create a new object Change an object

Generating SPS support bundle using REST

Basic settings

Retrieve basic firmware and host information Listing integrated products with SPS Firmware management

Retrieving information about SPS firmware image slots Testing new SPS firmware before upgrade Upgrading SPS to a new firmware Uploading new firmware to SPS Downloading and installing SPS firmware through HTTP

Network settings

Network configuration options DNS servers Routing between interfaces Naming options Network addresses Routing table Local services of SPS Local services: Web login for administrators Local services: Web login for users Local services: cluster interface System backup policy Encrypting system backup policy

Date and time

Date & time NTP servers Timezone

Logs, monitoring and alerts

Management options

Web gateway authentication

Syslog server settings Disk fill-up prevention Mail settings Health monitoring SNMP settings SNMP traps Local services: access for SNMP agents Alerting System alerts Traffic alerts

Trust stores Enabling One Identity Safeguard Remote Access without Starling Join Managing Starling Join

Retrieving the status of services related to Starling Join/Unjoin

User management and access control

User management and access control Login settings Privileges of usergroups Audit data access rules Active sessions Manage users and usergroups locally on SPS Manage usergroups locally on SPS Manage users locally on SPS Configuring LDAP servers Configuring SPS login methods Configuring the SAML2 Service Provider settings

Managing SPS

Troubleshooting options Internal certificates Passwords stored on SPS Private keys stored on SPS Private keys generated on SPS Certificates stored on SPS Local services: enabling SSH access to the SPS host Manage the SPS license Change contact information Splunk integration Splunk integration Manage SPS clusters

Promote a SPS node to be the Central Management node in a new cluster Join node(s) to the cluster Query join status Assign a role to a node Query nodes Query one particular node Query the status of all nodes in the cluster Query the status of one particular node Upload and enable a configuration synchronization plugin Disable a configuration synchronization plugin

Configuration tools in SPS

Resolving hostnames to IP addresses Testing LDAP server connection

General connection settings

Channel policy Policies Archive/Cleanup policy

Running audit data cleanup policies immediately

Audit policies Backup policy Real-time content monitoring with Content Policies LDAP servers Signing CA policies Time policy Trusted Certificate Authorities Local user databases User lists

HTTP connections

HTTP connections HTTP connection policies HTTP channels HTTP authentication policies Global HTTP options HTTP settings policies Creating custom HTTP error templates Uploading a custom logo to your custom HTTP proxy error pages

Citrix ICA connections

ICA connections ICA connection policies ICA channels Global ICA options ICA settings policies

MSSQL connections

Limitations in handling MSSQL connections MSSQL connections MSSQL connection policies MSSQL channels MSSQL authentication policies Global MSSQL options MSSQL settings policies

RDP connections

RDP connections RDP connection policies RDP channels Configuring domain membership Global RDP options RDP settings policies

SSH connections

SSH connections SSH connection policies SSH channels SSH authentication policies Global SSH options SSH settings policies SSH host keys and certificates

Telnet connections

Telnet connections Telnet connection policies Telnet channels Telnet authentication policies Global Telnet options Telnet pattern sets Telnet settings policies

VNC connections

VNC connections VNC connection policies VNC settings policies Global VNC options

Search, retrieve, download, and index sessions

Audited sessions Download audit trails Searching in the session database with the basic search method Retrieving all sessions from the session database with the advanced search method Retrieving user information from the recorded sessions Searching in connection content Generate and retrieve screenshot for content search Session statistics Session histogram Session alerts Session events Indexing sessions Session audit trail downloads Local services: configuring the indexer Indexer policies

Reporting

Reporting Reports Built-in subchapters Pre-defined reports Content subchapters Available search fields

Health and maintenance

Monitor appliance health status Monitor indexer service status

Advanced authentication and authorization

Usermapping policy Plugins

Upload a plugin Delete a plugin Check the integrity of a plugin

Authentication and authorization plugins

Configuring Authentication and Authorization plugin instances

Credential store plugins Credential stores

Completing the Welcome Wizard using REST

Enable and configure analytics using REST

Enable One Identity Safeguard for Privileged Analytics Configure One Identity Safeguard for Privileged Analytics

REST API examples

Examples

Retrieve user information

Using the SPS REST API > Retrieve user information

You can check the endpoints and methods that a particular user is authorized to access.

Prerequisites:

The user must be logged in.

URL

GET https:<IP-address-of-SPS>/api/user_info

Cookies

Cookie name	Description	Required	Values
session_id	Contains the authentication token of the user	Required	The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For more information on authentication, see Authenticate to the SPS REST API. NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format).

Sample request

The following command retrieves user information from SPS about the logged in user, using the session ID received during the authentication.

Querying user info request

This information is also available on the /api/user/info and /api/user_info endpoints.

Response

If the user information is retrieved successfully, the response is the following.

Querying user info response

For more information on the meta object, see Message format.

Element		Type	Description
login_method		string	The user's login method during authentication.
	login_method.authentication	string	This field defines the type of the authentication. The possible values are: local, ldap, x509, radius, saml2.
	login_method.credential	string	This field defines the credential type. The possible values are: password, x509, local, cluster, federated.
	login_method.name	string	The name of the login method.
user			Top-level element, contains the details of the user whose access rights information has been retrieved.
	user.name	string	The user name of the logged-in user whose information has been retrieved.

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.

Code	Description	Notes
200	OK	User information has been retrieved successfully.
401	Unauthenticated	The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
403	Unauthorized	The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.

Checking the transaction status

Using the SPS REST API > Checking the transaction status

Before changing anything in the configuration of SPS, you must POST a request to open a transaction.

For details about the transaction model of SPS see How to configure SPS using REST.
To check the configuration changes you made in the transaction, see Reviewing the changelog of a transaction.

URL

GET https:<IP-address-of-SPS>/api/transaction/

Sample request

The following command retrieves the transaction status of SPS, using the session ID received during the authentication.

curl --cookie cookies --request GET https://<IP-address-of-SPS>/api/transaction

Response

The following is a sample response received if opening the transaction is successful.

{

              "body": {

                  "commit_message": "optional",

                  "status": "closed"

              },

              "key": "transaction",

              "meta": {

                  "href": "/api/transaction",

                  "parent": "/api"

              }

          }

Element	Type	Description	Notes
body.commit_message	enum	Commit messages can be used to add an explanation to every configuration change.	Possible values: required - the value of the commit_message parameter is required, if the require_commitlog parameter in /api/configuration/management/accounting is set to true. optional - the value of the commit_message parameter is optional, if the require_commitlog parameter in /api/configuration/management/accounting is set to false.
body.status	enum	The status of the current transaction. By default, or after a successful commit it is closed. After successfully opening a transaction, it is open.
key	string	Top level element, contains the details of the current transaction.

Element

Type

Description

Notes

body.commit_message

enum

Commit messages can be used to add an explanation to every configuration change.

Possible values:

required - the value of the commit_message parameter is required, if the require_commitlog parameter in /api/configuration/management/accounting is set to true.
optional - the value of the commit_message parameter is optional, if the require_commitlog parameter in /api/configuration/management/accounting is set to false.

body.status

enum

The status of the current transaction. By default, or after a successful commit it is closed. After successfully opening a transaction, it is open.

key

string

Top level element, contains the details of the current transaction.

For more information on the meta object, see Message format.

Open a transaction

Using the SPS REST API > Open a transaction

The REST API of SPS manages the changes of the configuration in transaction. You can open a transaction with a POST request, but the first change of the configuration will open the transaction automatically. For details about the transaction model of SPS see How to configure SPS using REST.

URL

POST https:<IP-address-of-SPS>/api/transaction

Cookies

Cookie name	Description	Required	Values
session_id	Contains the authentication token of the user	Required	The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For more information on authentication, see Authenticate to the SPS REST API. NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format).

POST body

Note that you must:

either send an empty body in the POST request,
or include a Content-Length: 0 header.

Otherwise the SPS REST server returns a 411 - Length Required error.

Sample request

The following command opens a new transaction on SPS, using the session ID received during the authentication.

curl -X POST --data "" --cookie cookies https://<IP-address-of-SPS>/api/transaction

Response

The following is a sample response received if opening the transaction is successful.

For more information on the meta object, see Message format.

{

  "meta": {

    "href": "/api/transaction",

    "parent": "/api"

  }

}

After opening a transaction successfully, the transaction status changes to open.

{

    "body": {

        "commit_message": "optional|required"

        "status": "open"

    },

    "key": "transaction",

    "meta": {

        "changes": "/api/transaction/changes",

        "href": "/api/transaction",

        "parent": "/api"

    }

}

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.

Code	Description	Notes
200	OK	Transaction opened successfully.
401	Unauthenticated	The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
403	Unauthorized	The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
405	MethodNotAllowed	You tried using an unsupported HTTP method. Use the POST method to open a transaction.
409	WebGuiOrConsoleConfigInProgress	The configuration of SPS is locked. Committing a new transaction is not allowed while another user is modifying configuration through interfaces other than the REST API. For example, web GUI, console, and so on.
411	UnsupportedMethod	You must send a body (which can be empty) in this POST request, otherwise the SPS REST server returns a 411 - Length Required error.

Commit a transaction

Using the SPS REST API > Commit a transaction

To submit your changes to SPS, you have to commit the transaction by using a PUT request with a JSON object. For details about the transaction model of SPS, see How to configure SPS using REST.

Note that committing a transaction locks the configuration of SPS similarly to accessing SPS from the web interface. For more information, see "Multiple users and locking" in the Administration Guide.

URL

PUT https:<IP-address-of-SPS>/api/transaction

Cookies

Cookie name	Description	Required	Values
session_id	Contains the authentication token of the user	Required	The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For more information on authentication, see Authenticate to the SPS REST API. NOTE: This session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format).

PUT body

The PUT request must include the following JSON object in its body.

{
  "status": "commit"
}

If the Basic Settings > Management > Accounting settings > Require commit log option is selected in the SPS web interface, you must include a commit message (a message object) in the request. This message will be visible on the Users & Access Control > Configuration History page of the SPS web interface. Note that on the Users & Access Control > Configuration History page, changes performed using the REST API are listed as changes to the REST server/REST configuration page.

{
  "status": "commit",
  "message": "My commit message"
}

Sample request

The following command commits a transaction to SPS, using the session ID received during the authentication.

curl -d '{"status": "commit","message": "My commit message"}' --cookie cookies -X PUT https://<IP-address-of-SPS>/api/transaction

Response

The following is a sample response received if committing the transaction is successful.

For more information on the meta object, see Message format.

After a successful commit, the transaction status changes to closed. To make other changes, you have to open a new transaction.

{
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  },
  "key": "transaction",
  "transaction": {
    "status": "closed"
  }
}

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.

Code	Description	Notes
200	OK	Transaction committed successfully.
401	Unauthenticated	The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
403	Unauthorized	The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
405	MethodNotAllowed	You tried using an unsupported HTTP method. Use the PUT method to commit a transaction.

Please select your product:

To serve you better, please complete the Purpose of your Chat:

Recommended Solutions for Your Problem

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

Retrieve user information

Prerequisites:

URL

Cookies

Sample request

Response

Status and error codes

Checking the transaction status

URL

Sample request

Response

Open a transaction

URL

Cookies

POST body

Sample request

Response

Status and error codes

Commit a transaction

URL

Cookies

PUT body

Sample request

Response

Status and error codes