# Create a new role within the specified scope

Creates a new role with specified permissions within the specified scope.

RBAC: requires Roles.Manage

Endpoint: POST /api/v1/rbac/scopes/{scope}/roles
Version: 1.0
Security: header

## Path parameters:

  - `scope` (string, required)
    Scope to filter permissions
    Example: "System or gr_05hxcvk1hjexere4pvtrj0hggt"

## Request fields (application/json):

  - `name` (string, required)
    Name of the role, unique within its scope
    Example: "user"

  - `description` (string,null)
    Optional description of the role's purpose and responsibilities
    Example: "The regular user"

  - `scope` (string, required)
    The scope in which the role is valid.
            The scope can be Global (hardcoded), currently the only one is "System".
            Also the scope can be dynamic, currently we use Group Id, like "gr_05hxcvk1hjexere4pvtrj0hggt"
    Example: "System"

  - `permissions` (object, required)
    Set of permissions to be assigned to this role

  - `permissions.resourceAccess` (array, required)
    List of type-safe resource-specific access controls

  - `permissions.resourceAccess.resource` (string, required)
    The type-safe resource being controlled

  - `permissions.resourceAccess.actions` (array, required)
    List of allowed type-safe actions for this resource

## Response 200 fields (application/json):

  - `roleId` (string, required)
    Unique identifier for the role
    Example: "\n        'admin',\n        'System:admin',\n        'rr_01hxcvk1hjexere4pvtrj0ymqq',\n        'System:rr_01hxcvk1hjexere4pvtrj0ymqq',\n        'gr_1lkjvfdoibb126576:rr_01hxcvk1hjexere4pvtrj0ymqq',\n    "

  - `name` (string, required)
    Name of the role, unique within its scope
    Example: "ADMIN"

  - `description` (string,null)
    Optional description of the role's purpose and responsibilities
    Example: "System administrator with full access"

  - `permissions` (object, required)
    Set of permissions assigned to this role

  - `permissions.resourceAccess` (array, required)
    List of type-safe resource-specific access controls

  - `permissions.resourceAccess.resource` (string, required)
    The type-safe resource being controlled

  - `permissions.resourceAccess.actions` (array, required)
    List of allowed type-safe actions for this resource

  - `createdAt` (string, required)
    Timestamp when the role was created
    Example: "2022-03-10T16:15:50Z"

  - `updatedAt` (string, required)
    Timestamp when the role was last updated
    Example: "2022-03-10T16:15:50Z"


## Response 400 fields