Access Control

Access control is facilitated through roles. Each role can contain multiple permissions.

Permissions

Each Permission has a resource path, describes actions, and whether the permission or allows or disallows access. The first example permits get for any resource operation within the API path /bots/.

Actions are based on lowercase versions of the HTTP Methods, get, post, put and delete. * allows all actions.

  {"path": "/bots/", "action": "get", "allow": true}

Permissions accumulate, the set below allows the get and post action for any resource under /bots/

[  
  {"path": "/bots/", "action": "get", "allow": true},
  {"path": "/bots/", "action": "post", "allow": true}
]

Permissions can deny access, this one gives access to any /bots resource, except /bots/21312.

[  
  {"path": "/bots/", "action": "get", "allow": true},
  {"path": "/bots/", "action": "post", "allow": true},
  {"path": "/bots/21312", "action": "*", "allow": false}
]

Wildcards can be used for dynamic parts of a path, /users/*/properties gives access to any path with three path components where the first one matches users and the last matches properties such as /users/4234324/properties

[  
  {"path": "/bots/", "action": "get", "allow": true},
  {"path": "/bots/", "action": "post", "allow": true},
  {"path": "/users/*/properties", "action": "get", "allow": true}  
]

Roles

A role groups permissions together Roles can be changed and the changes apply to a all role holders. Roles have a title, permissions and scope

A scope can have three different values:

• anonymous for non-authorized users. For example allow access to the registration endpoint.
• user-default assigned to users after registration. Note: this is a static assignment, if a new user-default role is being created it's not assigned to the existing users that had such a role assigned in the past.
• normal a role that be assigned to a user manually for various purposes.

{
  "title": "Anonymous User", 
  "scope": "anonymous", 
  "permissions": [
    {"path": "/users/register", "action": "post", "allow": true},
    {"path": "/users/login", "action": "post", "allow": true},
    {"path": "/users/trigger_verify_notification", "action": "post", "allow": true},
    {"path": "/users/verify", "action": "post", "allow": true},
    {"path": "/users/change_password_request", "action": "post", "allow": true},
    {"path": "/users/change_password_verify", "action": "post", "allow": true},
    {"path": "/users/*/change_email_verify", "action": "post", "allow": true},
    {"path": "/users/*/refresh_token", "action": "post", "allow": true},
    {"path": "/users/generate", "action": "post", "allow": true},
    {"path": "/requests", "action": "*", "allow": true}
  ]
}

An admin that can access any resource would look like that:

{
  "title": "admin",  
  "scope": "normal", 
  "permissions": [
    {"path": "/*", "action": "*", "allow": true}
  ]
}

There a special path key called auth_id to accommodate user ids, when a user with this role is accessing a resource auth_id is replaced by the users id when applied, a mechanism to allow a user only access to its own resources without have a different role for each user which would be impractical.

{
  "title": "user", 
  "scope": "user-default",
  "permissions": [
   {"path": "/users/auth_id", "action": "*", "allow": true},
    {"path": "/users/whoami", "action": "*", "allow": true}
  ]
}

HTTP Resources

GET /roles

Paginated lists of roles:

[
    {
      "_id": "txy3831ff9h",
      "title": "user", 
      "scope": "user-default",
      "permissions": [
       {"path": "/users/auth_id", "action": "*", "allow": true},
        {"path": "/users/whoami", "action": "*", "allow": true}
      ]
    },
      {
        "_id": "hxy1231ff9g",
        "title": "admin",
        "scope": "normal",
        "permissions": [
          {"path": "/*", "action": "*", "allow": true}
        ]
      }
]

POST /roles

Create a role.

{
  "title": "user", 
  "scope": "user-default",
  "permissions": [
   {"path": "/users/auth_id", "action": "*", "allow": true}
  ]
}

PUT /roles/:id

Update the role with the given id.

{
  "title": "new name", 
  "scope": "user-default",
  "permissions": [
   {"path": "/users/auth_id", "action": "*", "allow": true}
  ]
}

DELETE /roles/:id

Delete the role with the given id.