Skip to content
Leadtime
English
EnglishDeutschNot translated
Esc
↑↓navigate↵open⌘Jpreview

Replace role permissions

What this does: Completely replaces the permissions map for a custom role. This is a full replacement - all permissions must be specified in the request.

Important restrictions:

  • Base roles cannot have their permissions modified
  • Only custom roles can be updated
  • All permissions must be provided (this is a complete replacement)

Permission handling:

  • Permissions are automatically normalized (removed if false, kept if true)
  • Permissions are validated against disallowed permissions for the role type
  • Guest roles have restrictions on certain permissions
  • Invalid permissions are rejected with error messages

What must be provided:

  • permissions: Complete map of all permissions with boolean values
    • true: Permission is allowed
    • false: Permission is disallowed (will be removed from the map)

Permission inheritance:

  • If the role has a parent, you can override inherited permissions
  • Setting a permission to false explicitly disallows it (even if parent allows it)
  • Setting a permission to true explicitly allows it (overrides parent if parent disallows)

Use cases:

  • Bulk update all permissions for a role
  • Copy permissions from another role by providing its complete permission map
  • Reset role permissions to a known state
  • Apply permission templates to roles

Note: For updating a single permission, use PATCH /roles//permissions/ instead.

PUT/administration/roles/{id}/permissions
Authorization
AuthorizationOAuth2 access token · headerrequired
Scopes:api:write
or
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
permissionsobjectrequired

Complete map of permission keys to boolean values that replaces the entire permission set for the role. Keys are permission identifiers using dot notation (e.g., "projects.create", "tasks.delete"). Values are true to allow the permission or false to disallow it. This is a complete replacement - all permissions must be specified. Permissions set to false are removed from the role. Permissions are validated against disallowed permissions for the role type.

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.

401

Unauthorized - Invalid or missing authentication token

403

Forbidden - Insufficient API scopes or permissions

Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X PUT "https://leadtime.app/api/public/administration/roles/string/permissions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "permissions": {
    "projects.create": true,
    "projects.delete": false,
    "projects.edit": true
  }
}'
Response
{
  "createdAt": "2019-08-24T14:15:22Z",
  "createdBy": "string",
  "description": "Standard employee role",
  "editedAt": "2019-08-24T14:15:22Z",
  "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"
}