SAYMON is a multi-user system. To be safe in use, it has a mechanism that allows you to give 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, these rights are called 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.
Objects' and links' permissions
The first group of permissions includes two called
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.
How objects' and links' permissions work under the hood
Each time you make a request to an API method that requires you to have
linkPermissions, SAYMON runs an algorithm that checks whether you have those permissions. Before providing a description of the algorithm, let's introduce some terms and definitions. For simplicity, the term object is used 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
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.
referencePermissions group contains permissions that 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.
The third 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 are
manage-documents, etc. Here is a list of all items to which you may have the manage permissions:
manage-documents are subsets of
manage-links permissions. This means that users with
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:
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|
The table below summarizes all the mentioned about permissions' subsets:
+ 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.
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|
Some methods might require you to have multiple permissions. For example, a record
(create-objects | manage-objects) means that a method requires you to have permission to a specific object AND