The Sassafras REST API provides programmatic access to settings and objects on Sassafras AllSight, LabSight, and KeySight servers.

This document provides information on the REST methods and resources for version 2 of the API. The API should be used for basic querying of the data, and not for bulk or heavy-use data retrieval. There are currently other more efficient mechanisms for processes that require full data capture or continual bulk data access.

The easiest way to test the API is to use a program like curl, although for GET-based methods a browser will be sufficient. Tools like Postman are useful for more advanced API testing.

URI Pattern and the Resource Hierarchy

All REST APIs are intended to provide access to resources using predictable and consistent URIs. Clients of a REST API submit HTTP requests and receive the results of the request in well-defined formats. Each request operates on the specified resource according to the request's HTTP method, which can be one of GET, PUT, POST, PATCH, and DELETE. A REST API request URI follows the pattern:

https://server.sample.net/api/v2/resource-path?arguments

The resource-path gives the path to a unique resource. Requests can be made on resources at each level of the hierarchy, and the response will list the resources contained at that level. For example, a request made for the URI:

https://server.sample.net/api/v2

would return the resources available within version 2 of the API. When a request is made for a resource that is not a container, the response has just the single resource.

The arguments in the URI can supply:

• a query filter for selecting resources
• a list of fields that should be returned in the response
• other directives specific to the request

Response fields and query filters are covered below.

Request and Response Formats

When POSTing data, the commonly accepted format is JSON, although certain endpoints expect plain text or raw data. Requests should include a Content-Type header that indicates the actual format used, for example application/json for JSON formatted request bodies. With curl you can do this as follows:

curl --header "Content-Type: application/json" https://server.sample.net/api/v2/...

Responses will be formatted as JSON for most endpoints, although certain resource endpoints have different format types as appropriate. The response will always include a Content-Type header to indicate the format.

Responses with Content-Type application/json conform to a simple schema that supports individual objects and arrays of objects, where each object contains properties corresponding to the requested fields in addition to the resource ID and type.

When the response contains multiple resources, the resources are sent as members of a JSON array.

[
    { resource fields... },
    { resource fields... },
    ...
]

Responses with just one resource are sent without an enclosing array.

{
    resource fields...
}

Response Fields

Response data contains the resource ID and type by default. To receive other attributes of the resource, the attribute field names are given in the fields=... argument. Field names vary depending on the resource type, but all resources have ident and type fields. The ident can be used to request resources within the containing resource.

https://server.sample.net/api/v2/computer

This query would return a response listing all the sub-resources within the computer resource:

[
    { "ident":"items", "type":"topic" },
    { "ident":"sections", "type":"topic" },
    { "ident":"divisions", "type":"topic" },
    { "ident":"schema", "type":"topic" }
]

The list in the response gives resources that we can request within the computer resource. By default, list responses like this will only return the ident and type fields. To retrieve fields other than these, include the field names in the fields argument.

For leaf resources that do not contain other resources, the response will be a single object instead of a list of objects. In the next example we also include a fields argument, with field names separated by commas. The fields are specific to the resource type, product in this case:

https://server.sample.net/api/v2/product/items/5A55ADEF383F4E8798073862A18D3433?fields=Name,Version,Publisher

When a URI includes a fields argument, those fields will be included in the resource record (the ident and type fields are always included):

{
    "ident": "5A55ADEF383F4E8798073862A18D3433",
    "type": "product",
    "Name": "Microsoft Office 2008 for Mac Standard Edition",
    "Version": "2008",
    "Publisher": "Microsoft Corporation"
}

By default, a response with a single leaf resource will contain many fields other than ident and type. In this case, the fields argument can be used to reduce this default field set to just those that are required by the particular request. Furthermore, some resources have fields that are costly to gather and return. Such costly fields will only be included in the result when they are requested in the fields argument.

Valid field names for each resource type are listed in the description of each endpoint below, and also can be retrieved from the associated schema endpoints.

Query Filters

Endpoints that return a list of resources support a query filter that selects the set of resources that will be returned. Query filters use a typical format that includes common comparison and logical operators. Any top-level field defined for the resource type of the target endpoint can be used in the query filter. The query filter is provided in the query=... argument.

For example, a simple query filter on the computer/items endpoint can select just those computers that are in a particular division:

(Division="Some Division")

On the product/items endpoint, all products that are installed on at least 100 computers:

(InstallCount>=100)

On the report/items endpoint, the list of reports that were created more recently than a certain date:

(created>=@20220925000000Z)

Note the variations in syntax in these three examples. In the first example, since we are comparing with text string, that value is within quotation marks (it is valid to use either single or double quotation marks, as long as they are consistent). The second example is comparing a number, so there are no quotations marks around the value. The date in the third example demonstrates the required format: @YYYYMMDDhhmmssZ. Dates can be specified as UTC (suffix Z), or within a time zone (e.g., @20220925123000-0400, generally @YYYYMMDDhhmmss[+-]hhmm).

To test for non-zero or non-empty values, just use the field name:

(Anchored)

In addition to the usual comparison operators, there some useful substring operators available. In all cases the order of the operands is important: the string to be searched for on the left, the string to search on the right.

String prefix: ("needle"*=Haystack)

String suffix: ("needle"%=Haystack)

String containment: ("needle"~=Haystack)

All string comparisons and searches are case-insensitive.

More complex query filters can be built using logical operators. Use parentheses to indicate the order of operations. This query filter on the computer/items endpoint looks for all computers in the "Second Floor" division that are enabled for audits but have not audited since a certain date:

(Division='Second Floor')&&(Audited)&&(LastAudit<@20220925000000-0400)

Complex query filters can also use logical or || and negation !.

Case Insensitive Field Names

The API treats all field keys in a case-insensitive way. This means if you use a field like "Name" in a request body or in a query filter, it will be the same as if you had used "name" or "NAME". The field keys that are returned in responses will match how they were specified in the request's field parameter. If you send a request with fields=name, the response will include that field with the key "name". If you do not specify the field key but the field still appears in the response (e.g., with a GET request on a non-container resource when no fields parameter is given), the field key will use a consistent case from one request to another.

Although the API treats field keys as case-insensitive on the server side, many client-side environments (like JavaScript) are case-sensitive, so you must use the proper cases when referencing fields. The best way to ensure that you get the casing you require is to use the fields parameter to explicitly request the fields you will be using. Otherwise, make a test query to the endpoint to determine what the default casing is for a particular field, and use that.

Performance Considerations

Requests to endpoints that return a list of resources are expensive for the server to process. Every resource in the list must be loaded from the data, tested, and formattted for the resulting response. If you are making frequent requests to a list endpoint you should consider using the Bulk Query endpoints or other mechanisms that are more suited to bulk data retrieval, or that incorporate caching.

See the documentation for Scripting, ksODBC, ksJDBC, and exporting.

Requests to leaf endpoints that return a single object are more efficient (unless you make many many such requests), although requesting a full object with complex sub-fields creates additional server load. It is always best to request just those fields that are actually needed and consider caching the response data.

While it is possible to get all data for all objects in one query, making such a large request can be wasteful of server resources especially if the intent is to use only part of the data. It is best to request just the fields that are necessary for the task, and use a filter to reduce the number of items returned. If the query is being used to locate just one object, perhaps by name, it is best to search for the matching object once and cache the ID, then in subsequent queries use the ID to get the object directly.

Rate Limiting

Servers can be configured to limit the number of REST API calls that can be made over some period of time. When a request would cause this limit to be exceeded, it will fail with error code 429. The Retry-After header will indicate the number of seconds to wait before making the request again. Note that this rate limit is independent of who is making the request -- the same limit is shared and used by all accounts.

In most cases (and particularly for cloud-hosted servers) the primary purposes for the rate limit are to prevent abuse and curtail brute-force attacks. If your use of the REST API is significantly constrained by the rate limit, it is possible to increase the limit. If the server is self-hosted, the configuration can be changed by any admin with sufficient privileges. If the server is cloud-hosted by Sassafras, the limit can only be raised by contacting Sassafras Software.

The Sassafras REST API uses access tokens to authenticate and authorize requests. Access tokens are passed in the Authorization header of each API request as Bearer tokens.

For development and testing, it is possible to use HTTP Basic Auth for API requests. This option is not intended for production use since the account name and password must be provided to the code that is making the requests, and there is no mechanism for limiting the priviliges beyond what the account holds.

Access tokens represent the permissions granted to the account that created them, so it is important to store and use them securely. All API requests should be made over HTTPS in order to ensure the privacy of access tokens. Keeping access tokens secure is your responsibility.

When API calls are made within a web page, authentication can use existing credentials held by the browser (provided the user has connected to and authenticated with the API host server via the Web UI).

All API requests must have an Authorization header with valid credentials. When credentials are not present or invalid a 4xx level status response will be returned. A 4xx level status will also be returned when credentials are valid but the account does not have permission for the requested endpoint or resource.

See the following section on Token Endpoints for information on creating access tokens.

You can create an access token in the Web UI by selecting View Account or Edit Account from the account menu in the upper right of any page. Click the Get Access Token button, provide the requested information, click Create, and copy the resulting access token.

Each access token represents the permissions that have been granted to the account that created it. If the permissions for the account change, the access token will adopt these changes. An access token can contain a permissions scope that places further restrictions on the account's permissions. An access token's permission scope cannot add new permissions, it can only restrict the permissions held by the account.

An access token has a limited lifetime, after which it will no longer be valid. Furthermore, any internal account's previously issued access tokens can be immediately invalidated by changing that account's password.

With existing credentials (for example, an access token created within the Web UI), new access tokens can be created to extend API access into the future, or apply additional restrictions.

In support of API discovery, every container endpoint supports the GET method, which returns the list of topic endpoints within that container. Use the topic lists to browse through all the endpoints that are available (provided your account has the appropriate permissions). Note that some endpoints are not documented here. These endpoints are used internally, and might change without warning. If an undocumented endpoint looks like it might be of use to you, please contact Sassafras Software to discuss your use case.

Computer records are created for all computers that have the KeyAccess client software installed. Computer records can also be created by importing information from other sources such as Intune and Jamf, or by creating them with scripts or API calls. Computer IDs can be based on a MAC address, hardware serial number, computer name, or other quasi-unique system properties. The client determines the ID of a computer by stepping through an ordered list of "ID Types", using the first ID type that has a valid value for that computer's ID. Computer records that are imported or otherwise created without a client can use whichever ID makes the most sense. If the source data has the serial number of a computer, that is the recommended choice for the ID.

Computer records are not just created for physical hardware. For licensing purposes a computer record is also created for Thin-client connections so an RDP server that has the client installed. Computer records are also create for virtual computer instances that have the client installed.

While it is possible to delete Computer records, it is often best to leave them in the data and use the Login type or Lifecycle Stage to mark them as uninteresting. If the computer has the client software installed, the matching computer record will be recreated the next time the client on that computer communicates with the server. Deleting a computer record also removes some of the data that was collected for that computer, and removes that computer from various usage reporting. Such historical data might prove useful even once the computer has been removed from service.

Device records are created for certain devices discovered by the KeyAccess client on a computer. Device records can also be created by importing information from other sources such as Intune and Jamf, or by creating them with scripts or API calls. Device IDs are derived from a device's unique serial number.

Products are the primary object for recording software usage and gathering software audits. Products typically contain one or more executable programs, which are tracked by the client software when gathering usage data. Web Products reference URLs instead of executable programs for tracking browser activity. Products can also contain information for fonts as a way to audit where fonts are installed. Finally, a set of related products can be gathered into a family product for use in aggregating usage and audit information.

Products are automatically imported into a server based on what software has been discovered on the clients of that server. The information about these products is retrieved from Sassafras's Product Recognition Service (PRS), a collection of over 15,000 software products that is maintained and updated by Sassafras. The core definition of products imported from PRS should not be changed, since those changes can be removed if the products are re-imported for any reason. The core definition includes the programs, packages, fonts, URLs, and editions/families that make up the product; the product Name, Version, and Publisher; various other PRS-supplied information like Description and Category. There are non-core properties that are intended for customization and can be changed without issue, such as Web Description, External URL, External ID, Notes, and Tags. Of course any manual products created specifically on a server can be defined and changed as needed and will not be altered by PRS imports.

Policies are used to configure how the server should record software usage and enforce license limitations. A policy can have one of three actions: Manage, Observe, or Deny. A policy also has a Scope that defines where (or to whom) the policy applies. Each policy references a list of software products that are covered by that policy, and there can be multiple policies that reference the same product.