Roles

Role-based access control (RBAC) restricts network access based on a person's role within an organization and has become one of the main methods for advanced access control. The roles in RBAC refer to the levels of access that users have to the network.

GET/v1/roles

List roles

This endpoint allows you to retrieve a paginated list of all your roles.

Request

Optional query

Name
page
Type
integer
Description
The page number of roles returned.
- Default 1
Name
page_size
Type
integer
Description
The page size number of roles returned.
- Default 10

Response

Name
data
Type
array<object>
Description
Array of role object
Name
data._id
Type
string
Description
Unique identifier for the role.
Name
data.name
Type
string
Description
The name for the role.
Name
data.permissions
Type
array<string>
Description
The array of allowed permission name for the role.
Name
data.created_date
Type
datetime
Description
Datetime of when the role was created.
Name
data.created_by
Type
string
Description
User identifier who create the role.
Name
data.updated_date
Type
datetime
Description
Datetime of when the role was updated.
Name
data.updated_by
Type
string
Description
User identifier who update the role.
Name
pagination
Type
object
Description
Object of Pagination
Name
pagination.page
Type
number
Description
Page number.
Name
pagination.page_size
Type
number
Description
Number of total document per page.
Name
pagination.page_count
Type
number
Description
Total page count.
Name
pagination.total_document
Type
number
Description
Total filtered document.

Request

GET

/v1/roles

const response = axios.get('/v1/roles', {
  params: {
    page:1,
    page_size: 10
  }
})

Response

{
  "data": [
    {
      "_id": "637b569149e0c02e1036c35a",
      "name": "Super Admin",
      "permissions": ["role:create", "role:read"],
      "created_by": "637d83d15d2be122007524bf",
      "created_date": "2022-01-01T00:00:00.000Z",
    },
    {
      "_id": "637d83d15d2be122007524bf",
      "name": "Manager",
      "permissions": ["role:create", "role:read"],
      "created_by": "637d83d15d2be122007524bf",
      "created_date": "2022-01-01T00:00:00.000Z",
    },
  ],
  "pagination": {
    "page": 1,
    "page_size": 1,
    "page_count": 1,
    "total_document": 2
  }
}

POST/v1/roles

Create role

This endpoint allows you to add a new role.

Request

Required attributes

Name
name
Type
string
Description
The name for the role.
Name
permissions
Type
array<string>
Description
The array of allowed permission name for the role.

Response

Name
_id
Type
string
Description
Unique identifier for the role.

Request

POST

/v1/roles

const response = axios.post('/v1/roles', {
  name: "Administrator",
  permissions: ['role:create', 'role:read']
})

Response

{
  "inserted_id": "637d83d15d2be122007524bf"
}

GET/v1/roles/:id

Retrieve role

This endpoint allows you to retrieve a role by providing their id.

Response

Name
_id
Type
string
Description
Unique identifier for the role.
Name
name
Type
string
Description
The name for the role.
Name
permissions
Type
array<string>
Description
The array of allowed permission name for the role.
Name
created_date
Type
datetime
Description
Datetime of when the role was created.
Name
created_by
Type
string
Description
User identifier who create the role.
Name
updated_date
Type
datetime
Description
Datetime of when the role was updated.
Name
updated_by
Type
string
Description
User identifier who update the role.

Request

GET

/v1/roles/:id

const response = axios.get('/v1/roles/637d83d15d2be122007524bf')

Response

{
  "_id": "637d83d15d2be122007524bf",
  "name": "Manager",
  "permissions": ["role:create", "role:read"],
  "created_by": "637d83d15d2be122007524bf",
  "created_date": "2022-01-01T00:00:00.000Z",
}

PATCH/v1/roles/:id

Update role

This endpoint allows you to perform an update on a role.

Request

Optional attributes

Name
name
Type
string
Description
The name for the role.
Name
permissions
Type
array<string>
Description
The array of allowed permission name for the role.

Request

PATCH

/v1/roles/:id

const response = axios.patch('/v1/roles/637d83d15d2be122007524bf', {
  name: "Administrator",
  permissions: ['role:create', 'role:read']
})

Response

{
  "matched_count": 1,
  "modified_count": 1
}

DELETE/v1/roles/:id

Delete role

This endpoint allows you to delete roles from your role list.

Request

DELETE

/v1/roles/:id

const response = axios.delete('/v1/roles/637d83d15d2be122007524bf')

Response

{
  "deleted_count": 1
}

POST/v1/roles/:id/assign-permissions

Assign permissions

This endpoint allows you to perform an update on a role to assign permission.

Required attributes

Name
permissions
Type
array<object>
Description
The array of permission object for the role.
Name
permissions.name
Type
string
Description
The name for the permission.
Name
permissions.assign
Type
boolean
Description
The assign status true or false

Request

POST

/v1/roles/:id/assign-permissions

const response = axios.post('/v1/roles/637d83d15d2be122007524bf/assign-permissions', {
  permissions: [
    {
      name: 'role:create',
      assign: true
    },
    {
      name: 'role:read',
      assign: false
    }
  ]
})

Response

{
  "matched_count": 1,
  "modified_count": 1
}