Role Management API

Role Management API Documentation

Create Role

• POST /roles
  • Summary: Creates a new role with specified permissions. This endpoint requires admin permissions.
  • Security: Bearer Authentication
  • Request Body:
    • Content-Type: application/json
    • Schema:

      {
        "$ref": "#/components/schemas/Role"
      }

  • Responses:
    • 201 Created: Role created successfully.
    • 400 Bad Request: Invalid data provided.
  • Tags:
    • Role Management

Retrieve List of Roles

• GET /roles
  • Summary: Fetches a list of roles based on pagination and filters. Requires admin permissions.
  • Security: Bearer Authentication
  • Parameters:
    • Query Parameter:
      • Name: page
      • Description: Page number of the roles list.
      • Schema:

        {
          "type": "integer"
        }

    • Query Parameter:
      • Name: limit
      • Description: Number of roles per page.
      • Schema:

        {
          "type": "integer"
        }

  • Responses:
    • 200 OK:
      • Description: A list of roles.
      • Content:
        • Content-Type: application/json
        • Schema:

          {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Role"
            }
          }

    • 404 Not Found: No roles found.
  • Tags:
    • Role Management

Delete Roles by IDs

• DELETE /roles
  • Summary: Deletes roles based on a list of IDs provided in the request. Requires admin permissions.
  • Security: Bearer Authentication
  • Request Body:
    • Content-Type: application/json
    • Schema:

      {
        "type": "object",
        "properties": {
          "ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of role IDs to delete."
          }
        }
      }

  • Responses:
    • 200 OK: Roles deleted successfully.
    • 400 Bad Request: Invalid request format.
  • Tags:
    • Role Management

Create or Update Default Role

• POST /roles/default
  • Summary: Creates or updates the default role with all available permissions. Requires admin permissions.
  • Security: Bearer Authentication
  • Responses:
    • 201 Created: Default role created or updated successfully.
    • 400 Bad Request: Failed to create or update the default role.
  • Tags:
    • Role Management

Retrieve Role by ID

• GET /roles/{roleId}
  • Summary: Fetches a role by its ID. Requires admin permissions.
  • Security: Bearer Authentication
  • Parameters:
    • Path Parameter:
      • Name: roleId
      • Description: The ID of the role to retrieve.
      • Schema:

        {
          "type": "string"
        }

  • Responses:
    • 200 OK: Role retrieved successfully.
    • 404 Not Found: Role not found.
  • Tags:
    • Role Management

Update Role by ID

• PUT /roles/{roleId}
  • Summary: Updates the specified role's details by ID. Requires admin permissions.
  • Security: Bearer Authentication
  • Request Body:
    • Content-Type: application/json
    • Schema:

      {
        "$ref": "#/components/schemas/Role"
      }

  • Responses:
    • 200 OK: Role updated successfully.
    • 404 Not Found: Role not found.
  • Tags:
    • Role Management

Delete Role by ID

• DELETE /roles/{roleId}
  • Summary: Deletes the specified role by its ID. Requires admin permissions.
  • Security: Bearer Authentication
  • Responses:
    • 200 OK: Role deleted successfully.
    • 404 Not Found: Role not found.
  • Tags:
    • Role Management

Handles Unsupported Methods

• All Other Methods on /roles, /roles/default, and /roles/{roleId}
  • Summary: Handles unsupported methods for the respective endpoints.
  • Responses:
    • 405 Method Not Allowed: Method not supported.
  • Tags:
    • Role Management