Roles

Roles allow you to obtain fine-grained control over how users can access collections and entities in your app. In broad strokes, roles are created, and then assigned to users, who are then considered to be "members" of those roles. Collections and entities can specify which roles can access them, and have control over which type of access is allowed for which role.

For example, you could configure your app such that any user with a HumanResourcesDirector role is allowed to create new entities in the Employee collection, while the employees themselves can only read their own records, but not create new ones.

To understand how roles affect collection and entity access, see the Access Control guide.

Built-in Roles

Every app automatically contains a predefined All Users role. As the name implies, this role always contains all users of your app and can be useful when configuring permissions that should apply to all app users.

Role management

To create, read, update, and delete roles, use the /roles API. Roles have an automatically-generated string _id, as well as a user-configurable name and an optional description.

Create

To create a role, send a POST request to /roles/:appKey. The request body must include a non-empty name property of string type and may optionally include a description property of the same string type. Other properties are ignored, including _id, which is always auto-generated.

POST /roles/:appKey HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with master credentials]
Content-Type: application/json

{
  "name": "HumanResourcesDirector",
  "description": "Director-level employees at the Human Resources department"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "_id": "d6f7b2114aa3489891",
  "name": "HumanResourcesDirector",
  "description": "Director-level employees at the Human Resources department"
}

List and read

To list roles, send a GET request to /roles/:appKey. A successful response will contain an array of roles, each including an _id, a name, and optionally a description.

GET /roles/:appKey HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with master credentials]

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "_id": "d6f7b2114aa3489891",
    "name": "HumanResourcesDirector",
    "description": "Director-level employees at the Human Resources department"
  },
  {
    "_id": "7a18132a218a43c59",
    "name": "TechSupport",
    "description": "Tech support personnel"
  }
]

To fetch a specific role, send a GET request to /roles/:appKey/:roleId.

GET /roles/:appKey/d6f7b2114aa3489891 HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with master credentials]

HTTP/1.1 200 OK
Content-Type: application/json

{
  "_id": "d6f7b2114aa3489891",
  "name": "HumanResourcesDirector",
  "description": "Director-level employees at the Human Resources department"
}

Update

You can update the name or description of a role by sending a PUT request to /roles/:appKey/:roleId.

PUT /roles/:appKey/d6f7b2114aa3489891 HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with master credentials]
Content-Type: application/json

{
  "name": "HumanCapitalDirector",
  "description": "Director-level employees at the Human Capital department"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "_id": "d6f7b2114aa3489891",
  "name": "HumanCapitalDirector",
  "description": "Director-level employees at the Human Capital department"
}

Delete

To delete a role, send a DELETE request to /roles/:appKey/:roleId. Deleting a role causes it to be revoked from all users who were previously its members.

DELETE /roles/:appKey/d6f7b2114aa3489891 HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with master credentials]

HTTP/1.1 204 No Content

Role membership

Roles can be assigned to, and revoked from, either individual app users or multiple users in bulk. Any user who has permissions to read a role can assign it.

Assigning a role

You can assign a role to a single user or to multiple users at once.

Assigning to a single user

To assign a role to a single user, send a PUT request to /user/:appKey/:userId/roles/:roleId with an empty JSON body.

If the assignment is successful, you receive a 200 OK response containing the following role metadata:

• roleId—The _id of the role that was assigned to the user.
• grantedBy—The _id of the user who assigned the role. If the role was assigned using the master secret, the value is the app key.
• grantDate—The date and time at which the role was assigned to the user.

PUT /user/:appKey/59c40efa8af947/roles/d6f7b2114aa3489891 HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with master credentials]
Content-Type: application/json

{}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "roleId": "d6f7b2114aa3489891",
  "grantedBy": ":appKey",
  "grantDate": "2017-09-27T22:08:14.544Z"
}

Assigning in bulk

To assign a role to multiple users at once, send a POST request to /roles/:appKey/:roleId/membership with a JSON request body containing a non-empty array of string user _ids.

If the request is successful, you receive a 200 OK response with a JSON body indicating the number of users the role has been assigned to.

POST /roles/:appKey/d6f7b2114aa3489891/membership HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with master credentials]
Content-Type: application/json

{
    "userIds" : [ "59c40efa8af947", "8686dd3d4399463c" ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "assignedCount": 1
}

Revoking a role

To revoke a role from a user, send a DELETE request to /user/:appKey/:userId/roles/:roleId. If the request is successful, you receive a 204 No Content response.

DELETE /user/:appKey/59c40efa8af947/roles/d6f7b2114aa3489891 HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with master credentials]

HTTP/1.1 204 No Content

Listing a user's roles

To list all the roles that are currently assigned to a specific user, send a GET request to /user/:appKey/:userId/roles. If the request is successful, you will receive a 200 OK response containing an array of role metadata objects.

Listing a user's role only requires the requesting user to have permissions to read the user entity.

GET /user/:appKey/59c40efa8af947/roles HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with master credentials]

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "roleId": "d6f7b2114aa3489891",
    "grantedBy": ":appKey",
    "grantDate": "2017-09-27T22:08:14.544Z"
  },
  {
    "roleId": "7a18132a218a43c59",
    "grantedBy": "5bc176974dc04a13bf4f6e",
    "grantDate": "2017-08-25T20:01:24.364Z"
  }
]

You can also fetch the metadata for a specific role by sending a GET request to /user/:appKey/:userId/roles/:roleId.

Listing role members

To view data about members of a role (in other words, users who have been assigned the role), send a GET request to /roles/:appKey/:roleId/membership. A successful response includes an array of objects, each containing the _id of a user who has the role (in the userId property), the _id of the user who assigned the role to the above user (in the grantedBy property), and the date at which the role was granted (in the grantDate property).

GET /roles/:appKey/d6f7b2114aa3489891/membership HTTP/1.1
Host: baas.kinvey.com
Authorization: [Basic Auth with master credentials]

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "userId": "59c40efa8af947",
    "grantedBy": ":appKey",
    "grantDate": "2017-09-27T22:08:14.544Z"
  },
  {
    "userId": "8686dd3d4399463c",
    "grantedBy": ":appKey",
    "grantDate": "2017-09-27T23:36:57.658Z"
  }
]

Collection permissions

With the introduction of roles, collection permissions have been updated to use role-based access controls. This allows for much finer-grain control over collection and entity access. To learn more, see the collection permissions section of the Access Control guide.

In particular, the examples section offers an idea of how you might model real-life use cases using this feature.