Permissions

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. Additionaly, default user permissions can be confgured in the server.user.template.permissions parameter of the server configuration.

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 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.

How objects' and links' permissions work under the hood

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 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.

Permission algorithm

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.

Entities permissions

API methods that work with both objects and links (for example, Get Entity by ID) require entityPermissions. These methods check for permissions depending on the type of entity being accessed. If the user tries to access an object with those methods, SAYMON will check if this user has objectPermissions; if the user tries to access a link – linkPermissions.

The rest of the algorithm is the same as objectPermissions or linkPermissions.

Reference permissions

The 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.

Manage permissions

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 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 manage-properties and manage-documents 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 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.

See Also