API Documentation

Permissions

Role Types

Every User in the system, when attached to a Company through the UserPermission record, is assigned a role_type, which will be any of the following:

• Admin
• Basic
• Suspended

A user's role_type defines how they are able to interact with a Company's data.

Admin role types have unlimited access to all company's they have an active UserPermission (also known as an employment connection) on. This includes permission to read, write, delete nearly all information contained within that company.

A user with a Basic role type by default has access to almost not company data, except in cases where the data is related to him, or related to a Project or Service, and that user holds a Personnel Role on that job, with specific role-based permissions.

Module Permissions

ABasic user can be assigned any number of Module level permissions. API resources are categorized into Modules, and users can be assigned a Read or Write permission for each module. A Basic user with Read permissions on a module, will have read access to all of the records within the given module, for that connected company. In practice this means unrestricted access to /get & /find endpoints, as well as any non-standard endpoint accessed using an HTTP GET method. Similarily, a Basic user with Write permissions on a module will have full access to /save, /save-batch, and /delete endpoints, as well as any non-standard endpoint that requires a HTTP POST request method.

Module Permission Exceptions

In many cases, a Basic user without specific module permissions will have access to an endpoint without needing any module permissions. This may be if the user is entitled to view/modify that data because it belongs to them, or if that endpoint is not specifically attached to a company (for example message threads are independant of any particular company), or if the endpoint needs to handle data access on a record-specific level. For example a user may be entitled to view TimeLog records on jobs they are attached to, but not all company-wide TimeLog records, so in this case the TimeLog/get endpoint has a module permissions exception, where module read permissions are not required, and result sets are restricted based on a user's specific access requirements.

The Permissions Hierchy

So given that there are multiple permission layers, the permissions hierchy follows this order when an API request is made:

1. Check if the API endpoint itself is public, or if it requires authentication
2. If authenticated is required, verify authentication (through api key or security token)
3. Check if a user is an Admin or Basic user
4. Check if the endpoint has a module permissions exception
5. If no exception, check that the user has a read or write permission applicable for the endpoint
6. Endpoint specific permissions