# Create a new role in the specified scope

Creates a new role with specified permissions within the specified scope. The scope can be 'global' for global roles or a group ID for group-scoped roles. The scope value in the request body is ignored — the scope query parameter is authoritative. Group-scoped roles cannot include restricted permissions (GroupRoles.Manage, Group.Delete).

RBAC:
- requires ANY of Roles.Manage, GroupRoles.Manage

Endpoint: POST /api/v1/rbac/roles
Version: 1.0
Security: header

## Query parameters:

  - `scope` (string, required)
    Scope: 'System' for global roles, or a group ID.
    Example: "global 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 "global".
            Also the scope can be dynamic, currently we use Group Id, like "gr_05hxcvk1hjexere4pvtrj0hggt"
    Example: "global"

  - `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
    Enum: "AIAgents", "AIModels", "AIProviders", "AdminSettings", "AppData", "Apps", "Audit", "Data", "Emojis", "Federation", "Group", "GroupAIAgents", "GroupAIModels", "GroupAIProviders", "GroupApps", "GroupChannels", "GroupData", "GroupMembers", "GroupQuestions", "GroupReports", "GroupRoles", "GroupSettings", "Integrations", "Jobs", "Reports", "Roles", "Rules", "Signups", "Uploads", "Users"

  - `permissions.resourceAccess.actions` (array, required)
    List of allowed type-safe actions for this resource
    Enum: "Delete", "Impersonate", "Invite", "Manage", "Moderate", "Post", "PostAsChannel", "PostsRead", "Read", "UpdateStats"

## 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
    Enum: "AIAgents", "AIModels", "AIProviders", "AdminSettings", "AppData", "Apps", "Audit", "Data", "Emojis", "Federation", "Group", "GroupAIAgents", "GroupAIModels", "GroupAIProviders", "GroupApps", "GroupChannels", "GroupData", "GroupMembers", "GroupQuestions", "GroupReports", "GroupRoles", "GroupSettings", "Integrations", "Jobs", "Reports", "Roles", "Rules", "Signups", "Uploads", "Users"

  - `permissions.resourceAccess.actions` (array, required)
    List of allowed type-safe actions for this resource
    Enum: "Delete", "Impersonate", "Invite", "Manage", "Moderate", "Post", "PostAsChannel", "PostsRead", "Read", "UpdateStats"

  - `isAdmin` (boolean)
    Whether this custom role has admin-level permissions. For group-scoped roles, compared against GROUP_MEMBER baseline. For global-scoped roles, compared against SYSTEM_USER baseline. Auto-computed at creation/update time.
    Example: true

  - `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