---
search:
  tags:
    - administration
    - POST
seo:
  description: >-
    What this does: Creates a new custom role in the workspace. Custom roles…
    Reference for the POST /administration/roles endpoint in the Leadtime Public
    API API.
sidebar:
  badge: POST
  label: Create role
title: Create role
type: openapi-operation
---
**What this does:**
Creates a new custom role in the workspace. Custom roles can be edited and deleted, unlike base roles which are system-defined and read-only.

**Role types:**
- **normal**: For internal team members (employees, managers, etc.)
- **guest**: For external users like clients or partners with restricted access

**Permission inheritance:**
- Set a parent role ID to inherit permissions from that role
- Inherited permissions can be overridden by explicitly setting them in the permissions map
- This allows creating role variants without duplicating permission configurations

**Permission validation:**
- Permissions are automatically validated against disallowed permissions for the role type
- Guest roles have restrictions on certain permissions (e.g., cannot manage workspace settings)
- Invalid permissions are rejected with appropriate error messages

**Required fields:**
- name: Display name for the role
- icon: Icon identifier (e.g., "ri-user-star-line" or ":person_in_tuxedo:")
- type: Either "normal" or "guest"

**Optional fields:**
- description: Human-readable description of the role's purpose
- parentId: ID of parent role for permission inheritance
- permissions: Map of permission keys to boolean values (inherited from parent if not specified)

**What is returned:**
Returns the complete role details including the generated role ID, creation timestamp, and all permissions (including inherited ones).

**Use cases:**
- Create specialized roles for specific teams or departments
- Set up guest roles for external collaborators
- Build role templates that can be customized per workspace

<Operation source="api-reference" id="rolescontroller-createrole" />