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 permissions. This means that users with manage-objects permissions are automatically given the latter two permissions 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

upload-documents

upload documents

create-documents

create a URL to a document

modify-documents

modify a document's URL

delete-documents

delete documents and documents' URLs.

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

Items/Permissions' subsets

manage

create

modify

delete

upload

objects

+

+

+

+

-

links

+

+

+

+

-

flows

+

+

+

+

-

properties

+

+

+

+

-

documents

+

+

+

+

+

service-properties

+

-

-

-

-

users

+

-

-

-

-

classes

+

-

-

-

-

event-log

+

-

-

-

-

history

+

-

-

-

-

configuration

+

-

-

-

-

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

upload-agent-updates

upload updates for agents

run-bulks

run bulk operations

execute-operations

execute operations for an object or a link

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.