Chat now with support
Chat with Support

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

Introduction Using the Safeguard for Privileged Sessions REST API Basic settings User management and access control Managing Safeguard for Privileged Sessions General connection settings HTTP connections Citrix ICA connections RDP connections SSH connections Telnet connections VNC connections Search, download, and index sessions Reporting Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST About us Third-party contributions

Checking the transaction status

Before changing anything in the configuration of Safeguard for Privileged Sessions, you must POST a request to open a transaction.

URL
GET https:<IP-address-of-Safeguard for Privileged Sessions>/api/transaction/
Sample request

The following command retrieves the transaction status of Safeguard for Privileged Sessions, using the session ID received during the authentication.

curl --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/transaction

Response

The following is a sample response received if opening the transaction is successful. For details of the meta object, see Introduction.

{

  "key": "transaction",

  "meta": {

    "href": "/api/transaction",

    "parent": "/api"

  },

  "transaction": {

    "status": "closed"

  }

}
Element Type Description
transaction Top level element, contains the details of the current transaction
status string The status of the current transaction. By default, or after a successful commit it is closed. After successfully opening a transaction, it is open

Open a transaction

Before changing anything in the configuration of Safeguard for Privileged Sessions, you must POST a request to open a transaction. For details about the transaction model of Safeguard for Privileged Sessions see How to configure Safeguard for Privileged Sessions using REST.

Note that opening a transaction locks the configuration of Safeguard for Privileged Sessions similarly to accessing Safeguard for Privileged Sessions from the web interface. For details, see "Multiple users and locking" in the Administration Guide.

URL
POST https:<IP-address-of-Safeguard for Privileged Sessions>/api/transaction
Headers
Header 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 details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions 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 Safeguard for Privileged Sessions REST server returns a 411 - Length Required error.

Sample request

The following command opens a new transaction on Safeguard for Privileged Sessions, using the session ID received during the authentication.

curl -X POST --data "" --cookie cookies https://<IP-address-of-Safeguard for Privileged Sessions>/api/transaction
Response

The following is a sample response received if opening the transaction is successful. For details of the meta object, see Introduction.

{
  "meta": {
    "href": "/api/transaction",
    "parent": "/api"
  }
}

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

{
    "body": {
        "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 Using the Safeguard for Privileged Sessions REST API.

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.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the POST method to open a transaction.
409 WebGuiOrRpcApiConfigInProgress The configuration of Safeguard for Privileged Sessions is locked. Opening 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 Safeguard for Privileged Sessions REST server returns a 411 - Length Required error.

Commit a transaction

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

URL
PUT https:<IP-address-of-Safeguard for Privileged Sessions>/api/transaction
Headers
Header 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 details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions 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 AAA > Settings > Accounting settings > Require commit log option is selected in the Safeguard for Privileged Sessions web interface, you must include a commit message (a message object) in the request. This message will be visible on the AAA > Accounting page of the Safeguard for Privileged Sessions web interface. Note that on the AAA > Accounting 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 Safeguard for Privileged Sessions, using the session ID received during the authentication.

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

The following is a sample response received if committing the transaction is successful. For details of the meta object, see Introduction.

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 Using the Safeguard for Privileged Sessions REST API.

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.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the PUT method to commit a transaction.

Delete a transaction

To delete your changes, you have to delete the transaction. This is similar to the rollback transaction in SQL. For details about the transaction model of Safeguard for Privileged Sessions, see How to configure Safeguard for Privileged Sessions using REST. Deleting the transaction also deletes the configuration lock of Safeguard for Privileged Sessions.

URL
DELETE https:<IP-address-of-Safeguard for Privileged Sessions>/api/transaction
Headers
Header 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 details on authentication, see Authenticate to the Safeguard for Privileged Sessions REST API.

Note that this session ID refers to the connection between the REST client and the Safeguard for Privileged Sessions REST API. It is not related to the sessions that Safeguard for Privileged Sessions records (and which also have a session ID, but in a different format).
Sample request

The following command deletes a transaction, reverting the configuration to the state it was in when the transaction was opened, or to the current configuration available on Safeguard for Privileged Sessions (if another user has modified it since you opened the transaction).

curl --cookie cookies -X DELETE https://<IP-address-of-Safeguard for Privileged Sessions>/api/transaction
Response

The following is a sample response received if deleting the transaction is successful. For details of the meta object, see Introduction.

{
  "meta": {
    "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 Using the Safeguard for Privileged Sessions REST API.

Code Description Notes
200 OK Transaction deleted 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.
401 AuthenticationFailure Authenticating the user with the given credentials has failed.
405 UnsupportedMethod You tried using an unsupported HTTP method. Use the DELETE method to reset a transaction.
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating