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 needs only to monitor 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 the 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 [WIP]

There is also the so-called referencePermissions. They might be required only for references. If a reference requires this permissions, 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 is 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 cannot be assigned the upload permission subset.

Other permissions

The last group includes three permissions:
Permission title
What a permission allows users to do
execute-operations
execute operations for an object or a link
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.
Last modified 5mo ago