Partially update role

What this does: Updates only the specified fields of a custom role. Fields that are not provided remain unchanged. This is useful for making small adjustments without resending the entire role configuration.

Important restrictions:

Base roles (Root, CEO, Team Leader, Staff, Guest) cannot be updated
Only custom roles can be modified
Permissions cannot be updated via this endpoint (use PUT /roles//permissions or PATCH /roles//permissions/)

What can be updated:

name: Change the role display name
description: Update the role description
icon: Change the role icon
parentId: Change the parent role (permissions will be inherited from new parent)
type: Change role type between normal and guest

What happens:

Only provided fields are updated
Unspecified fields keep their current values
If parentId is changed, permissions are recalculated based on the new parent
Role metadata (editedAt) is automatically updated

Use cases:

Rename a role without changing permissions
Update role description or icon
Change role type (e.g., convert normal role to guest role)
Reassign parent role for permission inheritance

Note: To update permissions, use PUT /roles//permissions or PATCH /roles//permissions/.

PATCH/administration/roles/{id}

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:write

AuthorizationBearer token (JWT) · headerrequired

Path parameters

idstringrequired

Query parameters

fieldsToReturnstring

Comma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.

responseShapestring

Advanced override. Omit for the endpoint compact default. Use full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:compactfull

Header parameters

LT-Response-Shapestring

Advanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:full

Request body

requiredapplication/json

descriptionstring

Human-readable description explaining the role purpose and responsibilities. Maximum 400 characters. If provided, updates the description. If not provided, the existing description is kept.

iconstring

Icon identifier for the role. Can be a RemixIcon class name (e.g., "ri-user-star-line") or an emoji code (e.g., ":person_in_tuxedo:"). If provided, updates the icon. If not provided, the existing icon is kept.

namestring

Display name for the role. If provided, updates the role name. If not provided, the existing name is kept.

parentIdstring

ID of the parent role for permission inheritance. If provided, changes the parent role and permissions are recalculated based on the new parent. If not provided, the existing parent is kept. Must not create circular dependencies (cannot set a child role as parent).

typestring

Role type determines the intended use case and permission restrictions. "normal" roles are for internal team members. "guest" roles are for external users and have additional permission restrictions. If provided, changes the role type. If not provided, the existing type is kept.

Allowed:normalguest

Responses

200

createdAtstring<date-time>

ISO 8601 timestamp indicating when this custom role was created. Only present for custom roles, not base roles.

createdBystring

User ID of the person who created this custom role. Only present for custom roles, not base roles.

descriptionstringrequired

Human-readable description of the role purpose and responsibilities, localized based on user language preference.

editedAtstring<date-time>

ISO 8601 timestamp indicating when this custom role was last modified. Only present for custom roles, not base roles.

effectivePermissionsobjectrequired

Permission map after resolving the full parent chain and child overrides.

iconstringrequired

Icon identifier for the role. Can be a RemixIcon class name (e.g., "ri-user-line") or an emoji code (e.g., ":person_in_tuxedo:"). Used for visual identification in role lists.

idstringrequired

Unique identifier for the role. Base roles have IDs containing underscore-prefixed identifiers (e.g., "_root_", "_ceo_", "_staff_"). Custom roles have workspace-prefixed IDs.

namestringrequired

Display name of the role, localized based on user language preference.

parentIdstring

ID of the parent role if this role inherits permissions from another role. Undefined if the role has no parent (e.g., base roles or top-level custom roles).

permissionsobjectrequired

Complete map of all permissions for this role. Keys are permission identifiers (e.g., "projects.create", "tasks.delete"). Values are true if the permission is explicitly allowed, false if explicitly disallowed, or missing if inherited from parent role. This map includes both explicitly set permissions and inherited permissions.

rawPermissionsobjectrequired

Permissions explicitly stored or defined on this role before inheritance.

readOnlybooleanrequired

Boolean flag indicating if this is a base role (system-defined) that cannot be modified or deleted. Base roles include Root, CEO, Team Leader, Staff, and Guest.

typestringrequired

Role type indicating the intended use case. "normal" for internal team members, "guest" for external users. Determines permission restrictions.

401Unauthorized - Invalid or missing authentication token

403Forbidden - Insufficient API scopes or permissions

Request

curl -X PATCH "https://leadtime.app/api/public/administration/roles/string" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Leads a delivery team",
  "icon": ":person_in_tuxedo:",
  "name": "Team Lead",
  "parentId": "workspace-id_employee",
  "type": "normal"
}'

const response = await fetch("https://leadtime.app/api/public/administration/roles/string", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "description": "Leads a delivery team",
  "icon": ":person_in_tuxedo:",
  "name": "Team Lead",
  "parentId": "workspace-id_employee",
  "type": "normal"
})
});

import requests

response = requests.patch(
    "https://leadtime.app/api/public/administration/roles/string",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "description": "Leads a delivery team",
  "icon": ":person_in_tuxedo:",
  "name": "Team Lead",
  "parentId": "workspace-id_employee",
  "type": "normal"
},
)

Response

{
  "createdAt": "2024-01-01T00:00:00Z",
  "createdBy": "string",
  "description": "Standard employee role",
  "editedAt": "2024-01-01T00:00:00Z",
  "effectivePermissions": {
    "profile.manage": true,
    "tasks.create": true,
    "tasks.delete": false
  },
  "icon": "ri-user-line",
  "id": "workspace-id_employee",
  "name": "Employee",
  "parentId": "workspace-id_admin",
  "permissions": {
    "projects.create": true,
    "projects.delete": false
  },
  "rawPermissions": {
    "tasks.create": true,
    "tasks.delete": false
  },
  "readOnly": false,
  "type": "normal"
}