SalesKing sports a multi-level Role system, where each role can have many permissions. Roles can be assigned on different levels, which are checked top-down:

On the first level your company is assigned roles by us, depending on your plan.

In multi user plans a company can create their own set of roles and map them to users or teams. Some level's might not exist or do not have roles(single user plan, no teams). 

Teams can be nested, with multiple users and roles on each level.

Roles directly assigned to a user override the ones from his team-tree (check stops on first user level). The last User-box actually does not have roles and is just visualizing the team members.

Basics

On access, all roles on all levels are collected and access is denied if a permission is NOT given on each level. A permission is a collection of privileges(actions) allowed within a context(resource), which is directly reflected by our url-scheme: permission to "clients create" => sk.eu/clients/new + sk.eu/clients/create

A sales-role should obviously be allowed to read clients, so one of it's permissions should grant access to the clients index(list) => salesking.eu/clients and the show action(detail view) => salesking.eu/clients/001

App permissions

An App SHOULD define only needed permissions in the scope-parameter for oAuth2 authorization-requests. Those permissions are shown to the user when granting app access. You can omit the scope-param, e.g. for tests or internal apps:

No scope Parameter == All permission of the current user are taken

Permissions are given space delimited, each consisting of a context-name optionally followed by(colon) a csv list of permission names.

scope=api/clients api/invoices:create,read,update,delete<br>api/clients = All permissions CRUD implicit
api/invoices:create,read,update,delete = CRUD explicit stated

Permissions to view companies/current and users/current are always added. Since apps can only directly query api-resources, they must be prefixed with api/xy to match the resource uri.

There is one exception, which applies to apps using our pubsub-channels. Those must also ask for non-prefixed permissions(invoices) to get informed about internal changes.

Lets say your app wants to create a client and therefore must be allowed to access api/clients:create, the check goes like this:

- Company? YES
-- App? YES
--- User? YES
---- Team? YES
----- Client is created

This can fail on any level f.ex if: 

• a user has only access to the interface(clients:create instead of api/clients:create), 
• a users team cannot access api/clients, or maybe 
• the user revokes some of the app permissions.

Access Token Lifetime

By default the returned access token is valid for one hour. You can also request a token with unlimited lifetime by adding the offline_access to the scope list.

scope=api/clients offline_access

Available Permissions

The global available permissions can be found at /api/auth_permissions. You can filter the permission list like /api/auth_permissions?q=api to show only api-related permissions. 

An entry in the list looks something like this: 

auth_permission: {
name: "read"
privilege_list: "index, print, show"
context_name: "api/orders"
full_name: "API Orders show"
}