Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 7.2.1 - 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

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
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 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.

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

{
  "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 Application level error codes.

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
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 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"
    }
  ]
}
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 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.

Defaults query parameter

You can use the ?defaults query parameter to get information about all default configuration values under /api/configuration. You can include this parameter in either a POST or a PUT request with a partial request body which contains only a few configuration fields, and then the API will respond with a configuration object which shows how the API would complete the partial request body with default values.

URL
https://<IP-address-of-SPS>/api/configuration/example?defaults
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).
Operations

HTTP method

URL

Description

Notes

POST

/api/configuration/example?defaults

Listing the default parameters of a resource before creating it

 

PUT

/api/configuration/example/resource?defaults

Listing the default parameters of a resource before modifying it

 

Sample request

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

curl --cookie cookies --request PUT --data '@-' https://<IP-address-of-SPS>/api/configuration/management/syslog?defaults <<'REQUEST'
{
    "receivers": [
        {}
    ]
}
REQUEST
Sample response
{
    "body": {
        "encryption": {
            "client_authentication": null,
            "trust_store": null
        },
        "include_node_id": true,
        "receivers": [
            {
                "address": {
                    "selection": "ip",
                    "value": "127.0.0.1"
                },
                "port": 1,
                "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"
    }
}

For more information on syslog servers, see Syslog server settings.

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

Sample request

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

curl --cookie cookies --request POST --data '@-' https://<IP-address-of-SPS>/api/configuration/ssh/authentication_policies?defaults <<'REQUEST'
{
    "backend": {
        "selection": "radius"
    }
}
REQUEST
Sample response
{
    "body": {
        "backend": {
            "authentication_protocol": "pap",
            "selection": "radius",
            "servers": [
                {
                    "address": {
                        "selection": "ip",
                        "value": "127.0.0.1"
                    },
                    "port": 1,
                    "shared_secret": {
                        "key": "",
                        "meta": {
                            "href": "/api/configuration/passwords"
                        }
                    }
                }
            ]
        },
        "gateway_methods": {
            "kerberos": false,
            "password": false,
            "public_key": false
        },
        "name": "unknown",
        "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"
    }
}

For more information on SSH authentication policies, see SSH authentication policies.

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

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 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.
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.
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating