Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 7.0.5.1 LTS - 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, download, and index sessions Reporting Health and maintenance Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST

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 SPS, see How to configure SPS using REST. Deleting the transaction also deletes the configuration lock of SPS.

URL
DELETE https:<IP-address-of-SPS>/api/transaction
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 SPS (if another user has modified it since you opened the transaction).

curl --cookie cookies -X DELETE https://<IP-address-of-SPS>/api/transaction
Response

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

{
  "meta": {
    "href": "/api/transaction",
    "parent": "/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.
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 DELETE method to reset a transaction.

Reviewing the changelog of a transaction

To review your changes, retrieve the changelog of the transaction. For details about the transaction model of SPS, see How to configure SPS using REST.

URL
GET https:<IP-address-of-SPS>/api/transaction/changes
Sample request

The following command retrieves the changelog of the transaction.

curl --cookie cookies https://<IP-address-of-SPS>/api/transaction/changes
Response

The response contains the list of changes performed in the transaction, as list of JSON objects. Every change has a type and a path, other elements depend on the type of the transaction. For example, when you delete an object, the changelog includes the deleted object in the old_value field.

Element Type Description
new_order list The new order of a list after the change. This field is available for reorder transactions.
new_value string or JSON object The value of the object after the change. For example, the new value of a parameter.
old_order string or JSON object The order of a list before the change. This field is available for reorder transactions.
old_value string or JSON object The value of the object before the change. For example, the value of a deleted object.
path string Path of the changed endpoint or object.
type string The type of the change. One of: create, delete, reorder, replace

The following is a sample response received if the changelog is empty.

{
  "meta": {
    "href": "/api/transaction/changes",
    "parent": "/api/transaction",
    "transaction": "/api/transaction"
  },
  "changes": []
}

The following is a sample changelog received after deleting a Channel policy.

{
  "meta": {
    "href": "/api/transaction/changes",
    "parent": "/api/transaction",
    "transaction": "/api/transaction"
  },
  "changes": [
    {
      "old_value": {
        "name": "deny",
        "rules": []
      },
      "path": "/api/configuration/ssh/channel_policies/94615110156697e93121f3",
      "type": "delete"
    }
  ]
}
Code Description Notes
200 OK Transaction changelog 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.
405 MethodNotAllowed You tried using an unsupported HTTP method. Use the GET method to retrieve the changelog a transaction.

Application level error codes

In addition to the standard HTTP status codes, in certain cases, the SPS REST server provides additional information in the response about the error. The following table contains a brief description of such errors. For more details, see the error object in the response body.

Code Description Notes
400 InvalidRequestBody The request body sent by the user has an invalid format. This may be an error with the encoding or the body is not a properly encoded JSON value.
400 ConfigTreeNotAvailable An error occurred while preparing the configuration tree for the REST API.
400 SyntacticError A value to be set is not accepted syntactically. The details section contains the path that was found to be invalid.
400 InvalidPath The path provided by the client contains a syntax error. Path components are restricted to contain only lowercase alphanumeric characters, the dash (-) and the underscore (_) characters. The details section contains the path that was attempted to be accessed, but could not be retrieved.
400 SemanticError The configuration contains semantic errors, inconsistencies or other problems that would put the system into an unreliable state if the configuration had been applied. The details section contains the errors that were found in the configuration.
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.
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.
404 NodeNotFound The requested endpoint does not exist in the configuration. The details section contains the path that you tried to access, but could not be retrieved.
404 NodeNotAvailable The requested endpoint exists in the configuration, however, it is not available directly. The details section contains the path that you tried to access, but could not be retrieved.
405 MethodNotAllowed An attempt was made to change a configuration subtree in an unsupported way. The method <method> is not allowed for this node.
409 MidAirCollisionSemanticError This error occurs when the configuration has been changed by another client between starting and committing a transaction, and the changes in the transaction would interfere semantically with the changes of that other user. The recommended strategy to resolve this error is to review the changes made in the failing transaction, then roll it back, start a new transaction, redo the changes, and finally, commit the new transaction.
409 WebGuiOrRpcApiConfigInProgress The configuration of SPS 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.
409 MidAirCollision This error occurs when the configuration has been changed by another client between starting and committing a transaction, and the changes in the transaction would overwrite or interfere with the changes of that other user. The recommended strategy to resolve this error is to review the changes made in the failing transaction, then roll it back, start a new transaction, redo the changes, and finally, commit the new transaction.
409 NoTransaction An attempt was made to change the configuration when no transaction was open.
409 DoubleTransaction This error is returned when the client attempts to open a transaction while another transaction of that client is already started.
417 Expectation Failed

If you receive the "417 - Expectation Failed" error code when using curl, use curl with the --http1.0 or the -H "Expect:" option.

500 CommitMessageMissing This error is returned when a commit message is required for committing a transaction, but it was not provided in the commit request.
500 TransactionCommitError Unexpected internal errors during committing a transaction are interpreted as TransactionCommitError.
500 AuthorizationError The request could not be authorized due to an unexpected internal error.

Navigating the configuration of SPS

The main starting point of navigating the SPS configuration using REST is the https:<IP-address-of-SPS>/api/configuration endpoint. If you query this endpoint, the response contains a list of other endpoints that you can follow to list the various resources of SPS, or to list the objects of a specific resource. For example, https:<IP-address-of-SPS>/api/configuration/rdp lists resources related to controlling the Remote Desktop (RDP) protocol, while https:<IP-address-of-SPS>/api/configuration/rdp/channel_policies lists the available RDP Channel Policies.

Note that when you want to create an object that references another object (for example, a Channel Policy that uses a Content Policy), then the referenced object (in this case, the Content Policy) must already exist. For details, see Create a new object.

To modify or delete an object, you need the ID of the object. For details, see Change an object and Delete an object.

The following is a sample command to query the https:<IP-address-of-SPS>/api/configuration endpoint, and a sample response.

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

Response status: 200
--- BEGIN RESPONSE BODY ---
{
  "meta": {
    "first": "/api/configuration",
    "href": "/api/configuration",
    "last": "/api/configuration",
    "next": null,
    "parent": null,
    "previous": null,
    "transaction": "/api/transaction"
  },
  "items": [
    {
      "key": "aaa",
      "meta": {
        "href": "/api/configuration/aaa"
      }
    },
    {
      "key": "alerting",
      "meta": {
        "href": "/api/configuration/alerting"
      }
    },
    {
      "key": "datetime",
      "meta": {
        "href": "/api/configuration/datetime"
      }
    },
    {
      "key": "http",
      "meta": {
        "href": "/api/configuration/http"
      }
    },
    {
      "key": "ica",
      "meta": {
        "href": "/api/configuration/ica"
      }
    },
    {
      "key": "local_services",
      "meta": {
        "href": "/api/configuration/local_services"
      }
    },
    {
      "key": "management",
      "meta": {
        "href": "/api/configuration/management"
      }
    },
    {
      "key": "network",
      "meta": {
        "href": "/api/configuration/network"
      }
    },
    {
      "key": "passwords",
      "meta": {
        "href": "/api/configuration/passwords"
      }
    },
    {
      "key": "plugins",
      "meta": {
        "href": "/api/configuration/plugins"
      }
    },
    {
      "key": "policies",
      "meta": {
        "href": "/api/configuration/policies"
      }
    },
    {
      "key": "private_keys",
      "meta": {
        "href": "/api/configuration/private_keys"
      }
    },
    {
      "key": "rdp",
      "meta": {
        "href": "/api/configuration/rdp"
      }
    },
    {
      "key": "reporting",
      "meta": {
        "href": "/api/configuration/reporting"
      }
    },
    {
      "key": "ssh",
      "meta": {
        "href": "/api/configuration/ssh"
      }
    },
    {
      "key": "telnet",
      "meta": {
        "href": "/api/configuration/telnet"
      }
    },
    {
      "key": "troubleshooting",
      "meta": {
        "href": "/api/configuration/troubleshooting"
      }
    },
    {
      "key": "trust_stores",
      "meta": {
        "href": "/api/configuration/trust_stores"
      }
    },
    {
      "key": "vnc",
      "meta": {
        "href": "/api/configuration/vnc"
      }
    },
    {
      "key": "x509",
      "meta": {
        "href": "/api/configuration/x509"
      }
    }
  ]
}
--- END RESPONSE BODY ---
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating