List roles

What are Roles? Roles define what users can see and do in the workspace. Each role has a set of permissions that control access to features like creating projects, managing tasks, viewing reports, and more.

What is returned: This endpoint returns all roles available in the workspace, including:

Base roles: System-defined roles that cannot be modified (Root, CEO, Team Leader, Staff, Guest)
Custom roles: User-created roles that can be edited and deleted

Role properties:

Each role includes name, description, icon, and type (normal or guest)
The readOnly flag indicates if a role is a base role (cannot be modified)
Parent role relationships show permission inheritance hierarchy
Roles are returned in the user’s preferred language

Use cases:

Display role selection dropdowns in user management interfaces
Show available roles when assigning permissions to users
Build role management interfaces that distinguish between base and custom roles

GET/administration/roles

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:read

AuthorizationBearer token (JWT) · headerrequired

Responses

200

Array of RoleListItem

descriptionstringrequired

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

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).

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 GET "https://leadtime.app/api/public/administration/roles" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch("https://leadtime.app/api/public/administration/roles", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
  }
});

import requests

response = requests.get(
    "https://leadtime.app/api/public/administration/roles",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    },
)

Response

[
  {
    "description": "Standard employee role",
    "icon": "ri-user-line",
    "id": "workspace-id_employee",
    "name": "Employee",
    "parentId": "workspace-id_admin",
    "readOnly": false,
    "type": "normal"
  }
]