Access Control Routes

This page provides the routes for managing roles in the application.

GET /role

Retrieves a list of all access control roles in the system for the logged in user's organization.

Description: This endpoint retrieves a list of all access control roles in the system for the logged in user's organization.

Authentication: Requires the OWNER role and read permissions.

Response:

• 200 OK with the list of access control roles returned

{
  "roles": [
    {
      "_id": "667e56f98ada0eae284b21c7",
      "createdBy": "667e52015767249ca5838bfa",
      "description": "Test role of organization",
      "name": "TEST ROLE",
      "orgId": "666141dbfe2a0781e76f6549",
      "scopes": ["read", "write"],
      "__v": 0
    }
  ]
}

Errors:

• 401 Unauthorized if the user is not authenticated or does not have the required permissions.
• 500 Internal Server Error if there is an issue getting the roles in the database.

Usage: To retrieve a list of all access control roles for the organization of the logged in user, send a GET request to /role.

POST /role

Creates a new role for the authenticated user's organization.

Description:

This endpoint creates a new role for the authenticated user's organization.

Authentication: Requires the OWNER role and write permissions.

Request Body:

{
  "description": "Test role created", // (string, required) The description of the role
  "name": "TEST", // (string, required) The name of the role
  "scopes": ["read"] // (array, required) The scopes of the role
}

Response:

• 201 Created with the new role returned

{
  "newRole": {
    "createdBy": "667e52015767249ca5838bfa",
    "description": "Test role created",
    "name": "TEST",
    "orgId": "666141dbfe2a0781e76f6549",
    "scopes": ["read"],
    "_id": "667e674167c110ca01317e93",
    "__v": 0
  }
}

Errors:

• 400 Bad Request if the request body is missing or invalid.
• 401 Unauthorized if the user is not authenticated or does not have the required permissions.
• 409 Conflict if the role already exists.
• 500 Internal Server Error if there is an issue creating the role in the database.

Usage: To create a new access control role for the authenticated user's organization, send a POST request to /role with a JSON request body containing the description,name and scopes for the new role.

PUT /role/:id

Updates an existing access control role by ID.

Description: This endpoint updates the details of an existing access control role with the provided ID.

Authentication: Requires the OWNER role and update and write permissions.

Parameters:

• id (required): The ID of the access control role to update.

Request Body:

{
  "name": "TEST2", // (string, optional) The name of the role
  "description": "Testing" // (string, optional) The description of the role
}

Response:

• 200 OK with the updated role returned

{
  "updatedRole": {
    "_id": "667e691667c110ca01317e9d",
    "createdBy": "667e52015767249ca5838bfa",
    "description": "Test role created",
    "name": "TEST2",
    "orgId": "666141dbfe2a0781e76f6549",
    "scopes": ["read"],
    "__v": 0,
    "updatedBy": "667e52015767249ca5838bfa"
  }
}

Errors:

• 400 Bad Request if the request body is missing or invalid.
• 401 Unauthorized if the user is not authenticated or does not have the required permissions.
• 409 Conflict if the role with the provided ID does not exist
• 500 Internal Server Error if there is an issue updating the role in the database.

Usage: To update an existing access control role, send a PUT request to /role/:id, replacing :id with the ID of the role you want to update. Include a JSON request body with the updated name, description and scopes fields.

DELETE /role/:id

Deletes an access control role by ID.

Description: This endpoint deletes an existing access control role with the provided ID.

Authentication: Requires the OWNER role and delete permissions.

Parameters:

• id (required): The ID of the access control role to delete.

Response:

• 200 OK with the deleted role returned

{
  "deletedRole": {
    "_id": "667e691667c110ca01317e9d",
    "createdBy": "667e52015767249ca5838bfa",
    "description": "Testing",
    "name": "TESTS",
    "orgId": "666141dbfe2a0781e76f6549",
    "scopes": ["read"],
    "__v": 0,
    "updatedBy": "667e52015767249ca5838bfa"
  }
}

Errors:

• 400 Bad Request if the url or parameter vdw is invalid.
• 401 Unauthorized if the user is not authenticated or does not have the required permissions.
• 500 Internal Server Error if there is an issue deleting the role in the database.

Usage: To delete an existing access control role, send a DELETE request to /role/:id, replacing :id with the ID of the role you want to delete.