lt.users

lt.users manages user accounts and their role assignments. lt.me covers the authenticated caller’s own preferences. See Identity.

list

const result = await lt.users.list({
  role: 'reviewer',
  roleType: 'admin',
  limit: 50,
});

List users with optional filters.

Parameters

Field	Type	Required	Description
role	string	No	Filter by role name
roleType	string	No	superadmin, admin or member
status	string	No	Filter by user status
search	string	No	Search term
limit	number	No	Max results
offset	number	No	Pagination offset

Returns: LTApiResult<{ users: User[], total: number }>

Auth: Not required.

get

const result = await lt.users.get({ id: 'user_123' });

Get one user by ID.

Parameters

Field	Type	Required	Description
id	string	Yes	User UUID

Returns: LTApiResult<User>. 404 if not found.

Auth: Not required.

create

const result = await lt.users.create({
  external_id: 'jane.doe',
  email: 'jane@example.com',
  display_name: 'Jane Doe',
  roles: [{ role: 'reviewer', type: 'member' }],
});

// A one-time user who sees and acts only on their own assigned row
await lt.users.create({
  external_id: 'new-user',
  roles: [{ role: 'customer-triage', type: 'member', read_scope: 'self', write_scope: 'self' }],
});

Create a user. Each role entry may carry the scope fields read_scope (self or all, default all) and write_scope (none, self or all, default all). Scope refines a member grant and is ignored for admin and superadmin. Write is a subset of read: write_scope=all requires read_scope=all.

Parameters

Field	Type	Required	Description
external_id	string	Yes	External system identifier (the login name)
email	string	No	Email address
display_name	string	No	Display name
password	string	No	Password for credential login
roles	{ role, type, read_scope?, write_scope? }[]	No	Initial role assignments. type is superadmin, admin or member
metadata	Record<string, any>	No	Arbitrary metadata

Returns: LTApiResult<User> with status 201. 409 if external_id exists.

Auth: Not required.

update

const result = await lt.users.update({
  id: 'user_123',
  display_name: 'Jane Smith',
  metadata: { department: 'engineering' },
});

Update a user’s profile fields. Only the fields you pass change.

Parameters

Field	Type	Required	Description
id	string	Yes	User UUID
email	string	No	New email
display_name	string	No	New display name
password	string	No	New password
status	string	No	New status
metadata	Record<string, any>	No	Replacement metadata object

Returns: LTApiResult<User>. 404 if not found.

Auth: Not required.

patchProperties

const result = await lt.users.patchProperties({
  id: 'user-uuid',
  set: { badgeSlug: 'operator-june', shift: 'night' },
  remove: ['legacy_pin'],
  rename: { station: 'station_affinity' },
});

Patch the user’s properties in one statement. Deleting is explicit (remove), an absent key is kept, and rename preserves the value. Identity-binding keys (the target facets of badge scan schemes) must be unique among active users. See Scan codes.

Parameters

Field	Type	Required	Description
id	string	Yes	User UUID
set	Record<string, unknown>	No	Keys to set
remove	string[]	No	Keys to delete
rename	Record<string, string>	No	Old key to new key

Returns: LTApiResult<User>. 400 for a malformed patch, 404 for an unknown user, 409 for an identity conflict.

Auth: Not required.

getSystemPropertyKeys

const result = await lt.users.getSystemPropertyKeys();
// result.data → { keys: ['badge_id'] }

List the property keys the platform resolves identities against: the target facets of enabled identity scan schemes.

Parameters: none.

Returns: LTApiResult<{ keys: string[] }>

Auth: Not required.

delete

const result = await lt.users.delete({ id: 'user_123' });

Delete a user.

Parameters

Field	Type	Required	Description
id	string	Yes	User UUID

Returns: LTApiResult<{ deleted: true }>. 404 if not found.

Auth: Not required.

getRoles

const result = await lt.users.getRoles({ id: 'user_123' });

List a user’s roles.

Parameters

Field	Type	Required	Description
id	string	Yes	User UUID

Returns: LTApiResult<{ roles: Role[] }>

Auth: Not required.

addRole

// See the whole queue, act only on own rows
const result = await lt.users.addRole({
  id: 'user_123',
  role: 'reviewer',
  type: 'member',
  read_scope: 'all',
  write_scope: 'self',
});

Assign a role to a user. read_scope sets which escalations a member sees in search; write_scope sets which they may claim, resolve or cancel. self means rows assigned to the member; all means the whole queue. Write is a subset of read. Both default to all and are ignored for admin and superadmin. The returned role includes both fields.

Parameters

Field	Type	Required	Description
id	string	Yes	User UUID
role	string	Yes	Role to assign
type	string	Yes	superadmin, admin or member
read_scope	string	No	self or all (default all)
write_scope	string	No	none, self or all (default all)

Returns: LTApiResult<UserRole> with status 201.

Auth: Not required.

removeRole

const result = await lt.users.removeRole({ id: 'user_123', role: 'reviewer' });

Remove a role from a user.

Parameters

Field	Type	Required	Description
id	string	Yes	User UUID
role	string	Yes	Role to remove

Returns: LTApiResult<{ removed: true }>. 404 if the role is not assigned.

Auth: Not required.

me.getPreferences

const result = await lt.me.getPreferences();
// { status: 200, data: { preferences: { pinnedViews: [...] } } }

Read the caller’s preferences. Takes an optional auth context as its only argument.

Parameters: none.

Returns: LTApiResult<{ preferences: Record<string, unknown> }>. {} when unset.

Auth: Required. The call targets the caller.

me.patchPreferences

const result = await lt.me.patchPreferences({
  patch: {
    pinnedViews: [
      { id: 'pin-x1', label: 'Needs service', url: '/escalations/available?role=service&jeopardy=1', badge: true },
    ],
  },
});

Shallow-merge a patch into the caller’s preferences: top-level keys overwrite whole, and null deletes a key. The merge is one guarded statement. The stored document is capped at about 32 KB (413 above it).

Parameters

Field	Type	Required	Description
patch	object	Yes	Keys to merge; a null value deletes its key

Returns: LTApiResult<{ preferences: Record<string, unknown> }>: the merged document.

Auth: Required. The call targets the caller.