---
title: "Create organization role"
method: POST
path: "/api/v1/organizations/{org_id}/roles"
tags: ["Roles"]
---

# Create organization role

`POST /api/v1/organizations/{org_id}/roles`

Creates a new role within the specified organization with basic configuration including name, display name, description, and permissions. Use this endpoint to define custom roles that can be assigned to users within the organization. You can create hierarchical roles by extending existing roles and assign specific permissions to control access levels. The role will be scoped to the organization and can be used for organization-specific access control.

## Path parameters

- `org_id` string, required

## Request body

- V1rolesCreateOrganizationRole
  - `description` string — Description of the organization's role
  - `display_name` string — Display name of the organization's role
  - `extends` string — Base role name for hierarchical roles
  - `name` string — Unique name of the organization's role
  - `permissions` string[] — List of permission names to assign to this role. Permissions must exist in the current environment.

## Response `201`

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

- RolesCreateOrganizationRoleResponse
  - `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.dev/scalekit/apis/scalekit-api-reference.md) · [All operations](https://skmtc.dev/scalekit/apis/scalekit-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scalekit/scalekit-api-reference/revisions/49af6b0b79c6/schema)