Getting Started with the TOS API

Overview

When you use the TOS API:

  • Access a resource by sending an HTTP request to the TOS server. The server replies with a response that either contains the data you requested, an HTTP status indicator, or both.

  • TOS APIs are organized by resources, as recommended by REST best practices. API resources are located at:

    • SecureTrack:

      https://<securetrack_ip>/securetrack/api/

    • SecureChange:

      https://<securechange_ip>/securechangeworkflow/api/securechange/

    • SecureApp:

      https://<secureapp_ip>/securechangeworkflow/api/secureapp/

    where <securetrack_ip>, <securechange_ip>, and <secureapp_ip> are the IP address of the host server running TOS.

  • Request a particular resource by appending a particular path to this base URL that specifies the resource.
  • Requests to the server must be sent over HTTPS, not HTTP.

  • You must authenticate to the TOS server using HTTP basic access authentication with a valid username and password. The permissions for the account you use for authentication apply to your API request.

    • SecureTrack - The user must be a RADIUS, LDAP or local SecureTrack user. Authentication for the SecureTrack REST API via TACACS is available, if SecureTrack is configured for TACACS authentication.
    • SecureChange and SecureApp - The user can be any user that has permissions for the action that is done by the API call.
  • You must specify the content-type header as either application/xml or application/json.

  • API Pagination is supported for many REST API calls that return large amounts of data, making it easier for you to manage the results. If the API has the optional parameters start and count, then pagination is supported for that API call.

    • start (parameter) - zero-based, specifies the starting element to include in the returned results
    • count (parameter) - specifies the number of elements actually included in the results

    For example, to retrieve elements 51-60 in your results, set start = 50, and count = 10.

    The DTO for the results will contain a count and total field. Use these returned values to determine how many paginated calls you will need to make to retrieve all the desired results.

    • count (DTO results field) - lists the actual number of elements included in the returned results
    • total (DTO results field) - lists the total number of elements available to be included in the returned results

    For example, if you set the start parameter to 120 and the total number of elements from the search is 128, then the DTO results fields will be set as: total = 128 and count = 8, because the returned results contain the last 8 elements of the total of 128 possible results.

  • Access to TOS functionality via the REST API is determined by the specific permissions granted to the username used for authentication, unless otherwise noted explicitly otherwise for a specific API. For example if you run get_devices, the API call will return only the devices you have permission to access. Additional information about user permissions can be found at:

  • For security reasons, the OPTION http method is not supported. Supported REST API methods will include: GET, POST, PUT, PATCH and DELETE.
  • For a list of valid characters, see API Input Validation

Response Formats

For each resource, you can get the response in these formats:

  • XML - add the .xml extension

    The default response format is XML.

  • JSON - add the .json extension

For the APIs listed below, when returning a JSON list with a single element, the API passes the element inside an array rather than as a single element. Source code will no longer have to handle returned results differently depending on whether it is a single element or an array of element. Strings like id of a device, that were previously returned as integers will now be returned as a string containing the number surrounded with double quotes. Empty lists that were previously omitted will now be included as empty arrays. The order in which the properties appear in the returned JSON might be different from previous TOS versions.

(This change does not apply to returned XML data.) The change to the JSON returned data applies to the following APIs:

Additional Resources

Getting Started

Postman Collections

Online Documentation

Code Examples and Demos

The Tufin Developer Community

https://community.tufin.com