Skip to content

Permissions

SAYMON is a multi-user system. To be safe in use, it has a mechanism that allows giving various access rights to different users. For example, administrators can have the right to create new users, set their access rights, modify objects, change a system configuration, etc. A regular user who only needs to monitor the data should have access only to their own objects.

To work with SAYMON through its API, you also may need to have special rights. For API methods, we will use the term permissions. If an API method requires you to have some permissions, they will be specified in a method's description.

By default, new users don't have special permissions. They can be managed by administrators through a web interface or using the corresponding API methods.

Permissions used in the SAYMON API

All permissions used in the SAYMON API can be divided into four groups.

The first group of permissions includes two called objectPermissions and linkPermissions. In simple words, they define whether you are allowed to perform operations on a particular object or link. The paragraph below contains a more detailed description of how these permissions work.

Each time you make a request to an API method that requires you to have objectPermissions or linkPermissions, SAYMON runs an algorithm that checks whether you indeed have such permissions. Before providing a description of the algorithm, let's introduce some terms and definitions. For simplicity, we will use the term object to describe both objects and links.

  • All objects in SAYMON form a graph. Each object has parent and children objects accessible via links. The algorithm uses links only to parent objects to traverse the graph.
  • Permissions to an object might be given/forbidden for you explicitly. A list of objects to which you are explicitly given permissions is called included, to which you are explicitly forbidden — excluded.
  • Permissions to an object might also be given/forbidden to you implicitly. If there exists a path from an object to its ancestor to which you are explicitly given access and this path doesn't contain excluded objects, you will have implicit access to this object. If such a path doesn't exist, you are implicitly forbidden to work with the object.

When you make a request to an API method requiring objectPermissions or linkPermissions, the algorithm first checks whether you have explicit permissions to the object. If you have, the request will be processed. Otherwise, the algorithm checks whether you have implicit permissions to the object by traversing the object's parents. If a path to an included ancestor is found, the request will be processed as well. If not, you will get the 403 error indicating that you don't have the required permissions.

Reference permissions

The referencePermissions are required to get, delete and update references. If a request requires this permission, this means that you need to have access to an object to which the reference belongs.

Manage permissions

The second group represents the so-called manage permissions. If you have the manage permissions to some item, you can create, modify, and delete this item. Examples of such permissions aremanage-objects, manage-properties, manage-documents, etc. Here is a list of all items to which you may have the manage permissions: objects, properties, documents, links, flows, users, service-properties, classes, event-log, history, configuration.

Note that manage-properties and manage-documents are subsets of manage-objects and manage-links permissions. This means that users with manage-objects or manage-links permissions are automatically given the latter two permissions for objects or links as well.

For some of the manage permissions, users may be given only a subset of them. For example, users may have only create-object permission, which allows only creating but not modifying or deleting objects. Here is a list of all items to which users may be given a subset (create, modify, delete) of the manage permissions: objects, properties, documents, links, flows.

One permission that's a bit different from the mentioned ones and should be described separately is manage-documents. The permission consists of four subsets:

Subset title What a subset allows users to do
create-documents create a URL to a document
delete-documents delete documents and documents' URLs
modify-documents modify a document's URL
upload-documents upload documents

The table below summarizes all the mentioned about permissions' subsets:

Items/Permissions' subsets manage create modify delete upload
classes + - - - -
configuration + - - - -
documents + + + + +
event-log + - - - -
flows + + + + -
history + - - - -
links + + + + -
objects + + + + -
properties + + + + -
service-properties + - - - -
users + - - - -

The + sign at the intersection of a row and a column means that a corresponding item can be given a respective permission subset. For instance, + at the intersection of properties and delete means that properties can have the delete subset permissions. Minus at the same row and at the next column denotes that properties can't be assigned the upload permission subset.

Other permissions

The last group includes four permissions:

Permission title What a permission allows users to do
execute-operations execute operations for an object or a link
read-session-log get information about users' sessions
run-bulks run bulk operations
upload-agent-updates upload updates for agents

Multiple permissions

Some methods might require you to have multiple permissions. For example, a record objectPermissions&(create-objects | manage-objects) means that a method requires you to have permission to a specific object AND create-objects OR manage-objects permission.