---
title: "Create new role in environment"
method: POST
path: "/api/v1/roles"
tags: ["Roles"]
---

# Create new role in environment

`POST /api/v1/roles`

Creates a new role within the environment with specified permissions and metadata. Use this endpoint to define custom roles that can be assigned to users or groups. You can create hierarchical roles by extending existing roles, assign specific permissions, and configure display information. Roles are the foundation of your access control system and determine what actions users can perform.

## Request body

- V1rolesCreateRole
  - `description` string — Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters.
  - `display_name` string — Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications.
  - `extends` string — Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role.
  - `name` string — Unique name identifier for the role. Must be alphanumeric with underscores, 1-64 characters. This name is used in API calls and cannot be changed after creation.
  - `permissions` string[] — List of permission names to assign to this role. Permissions must exist in the current environment. Maximum 100 permissions per role.

## Response `201`

Role created successfully. Returns the complete role object with system-generated ID and timestamps.

- RolesCreateRoleResponse
  - `role` V1rolesRole
    - `default_creator` boolean — Indicates if this role is the default creator role for new organizations.
    - `default_member` boolean — Indicates if this role is the default member role for new users.
    - `dependent_roles_count` integer — Number of roles that extend from this role (dependent roles count). Read-only field.
    - `description` string — Detailed description of the role's purpose and capabilities. Maximum 2000 characters.
    - `display_name` string — Human-readable display name for the role. Used in user interfaces and reports.
    - `extends` string — Name of the base role that this role extends. Enables hierarchical role inheritance.
    - `id` string — Unique system-generated identifier for the role. Immutable once created.
    - `is_org_role` boolean — Indicates if this role is an organization role.
    - `name` string — Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters.
    - `permissions` RolesRolePermission[] — List of permissions with role source information. Only included when 'include' parameter is specified in the request.
      - `create_time` string, date-time
      - `description` string
      - `id` string
      - `name` string
      - `role_name` string — Name of the role from which this permission was sourced
      - `update_time` string, date-time

---

[API](https://skmtc.net/scalekit/apis/scalekit-api-reference.md) · [All operations](https://skmtc.net/scalekit/apis/scalekit-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scalekit/scalekit-api-reference/revisions/a40d5d4650e5/schema)