Users API

Overview

The Users API manages user accounts, profiles, preferences, and authentication.

Queries

getAll

Get all users in the system.

const users = await api.user.getAll.query();

Permission Required: admin Response:

string

User unique identifier

name

string

Username

string

Email address

emailVerified

Date | null

Email verification timestamp

image

string | null

Profile image URL (base64 data URI or external URL)

selectable

Get users for selection in UI components.

const users = await api.user.selectable.query({
  excludeExternalProviders: true,
});

Parameters:

excludeExternalProviders

boolean

default:false

If true, only returns users with credentials provider

Authentication: Protected

search

Search users by name.

const users = await api.user.search.query({
  query: "john",
  limit: 10,
});

Permission Required: admin

query

string

required

Search query

limit

number

default:10

Maximum results (1-100)

getById

Get detailed user information.

const user = await api.user.getById.query({ userId: "user-id" });

Authentication: Protected (own user) or admin (any user) Response:

string

User ID

name

string

Username

string

Email address

emailVerified

Date | null

Email verification date

image

string | null

Profile image

provider

'credentials' | 'oidc' | 'ldap'

Authentication provider

homeBoardId

string | null

User’s default home board

mobileHomeBoardId

string | null

User’s mobile home board

firstDayOfWeek

number

First day of week (0 = Sunday, 1 = Monday)

pingIconsEnabled

boolean

Whether app ping icons are enabled

defaultSearchEngineId

string | null

Default search engine ID

openSearchInNewTab

boolean

Whether to open search in new tab

Mutations

initUser

Initialize the first admin user during onboarding.

await api.user.initUser.mutate({
  username: "admin",
  password: "secure-password",
  email: "admin@example.com",
});

Authentication: Onboarding procedure (no auth required during setup)

This endpoint is only available during initial onboarding. Once the first user is created, it becomes inaccessible.

register

await api.user.register.mutate({
  username: "newuser",
  password: "secure-password",
  email: "user@example.com",
  inviteId: "invite-id",
  token: "invite-token",
});

Authentication: Public (requires valid invite) Parameters:

username

string

required

Desired username

password

string

required

User password

string

required

Email address

inviteId

string

required

Invite ID

token

string

required

Invite token

Throws:

FORBIDDEN - Invalid or expired invite
CONFLICT - Username already taken

create

Create a new user (admin only).

await api.user.create.mutate({
  username: "newuser",
  password: "secure-password",
  email: "user@example.com",
  groupIds: ["group-id-1", "group-id-2"],
});

Permission Required: admin

groupIds

string[]

required

IDs of groups to add the user to

setProfileImage

Set user profile image.

await api.user.setProfileImage.mutate({
  userId: "user-id",
  image: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
});

Authentication: Protected (own user) or admin (any user) Parameters:

userId

string

required

User ID

image

string | null

required

Base64-encoded image data URI (max ~256KB) or null to remove

Validation:

Must be valid data URI with image MIME type
Supported formats: PNG, JPEG, GIF, WebP
Maximum size: ~256KB (base64 encoded)

editProfile

Edit user profile information.

await api.user.editProfile.mutate({
  id: "user-id",
  name: "newusername",
  email: "newemail@example.com",
});

Authentication: Protected (own user) or admin (any user)

Only users with credentials provider can change username and email. Users authenticated via OIDC/LDAP cannot modify these fields.

Parameters:

string

required

User ID

name

string

required

New username

string

New email address

Notes:

Changing email will reset emailVerified to null
Username must be unique among credentials users

changePassword

Change user password.

await api.user.changePassword.mutate({
  userId: "user-id",
  previousPassword: "old-password",
  password: "new-password",
});

Authentication: Protected Parameters:

userId

string

required

User ID

previousPassword

string

Current password (required when changing own password)

password

string

required

New password

Behavior:

Users changing their own password must provide previousPassword
Admins can change other users’ passwords without providing previous password
Only works for credentials provider users

changeHomeBoards

Set user’s home boards.

await api.user.changeHomeBoards.mutate({
  userId: "user-id",
  homeBoardId: "board-id-1",
  mobileHomeBoardId: "board-id-2",
});

Authentication: Protected (own user) or admin (any user) Parameters:

homeBoardId

string | null

Default home board ID

mobileHomeBoardId

string | null

Mobile home board ID

Validation:

User must have view access to the specified boards

changeSearchPreferences

Update search preferences.

await api.user.changeSearchPreferences.mutate({
  userId: "user-id",
  defaultSearchEngineId: "search-engine-id",
  openInNewTab: true,
});

Parameters:

defaultSearchEngineId

string | null

Default search engine ID

openInNewTab

boolean

Whether to open search results in new tab

changeColorScheme

Set user color scheme preference.

await api.user.changeColorScheme.mutate({
  colorScheme: "dark", // "light", "dark", or "auto"
});

changePingIconsEnabled

Toggle ping icons.

await api.user.changePingIconsEnabled.mutate({
  id: "user-id",
  pingIconsEnabled: true,
});

changeFirstDayOfWeek

Set first day of week.

await api.user.changeFirstDayOfWeek.mutate({
  id: "user-id",
  firstDayOfWeek: 1, // 0 = Sunday, 1 = Monday
});

Parameters:

firstDayOfWeek

number

required

First day of week (0-6, where 0 is Sunday)

delete

Delete a user account.

await api.user.delete.mutate({ userId: "user-id" });

Authentication: Protected (own user) or admin (any user)

This permanently deletes the user and all associated data. This action cannot be undone.

OpenAPI Endpoints

GET /api/users

curl -X GET https://your-homarr.com/api/users \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /api/users/selectable

curl -X GET https://your-homarr.com/api/users/selectable \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /api/users/search

curl -X POST https://your-homarr.com/api/users/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "john", "limit": 10}'

GET /api/users/

curl -X GET https://your-homarr.com/api/users/user-id-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /api/users

curl -X POST https://your-homarr.com/api/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "secure-password",
    "email": "user@example.com",
    "groupIds": ["group-id"]
  }'

PUT /api/users/profileImage

curl -X PUT https://your-homarr.com/api/users/profileImage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-id",
    "image": "data:image/png;base64,..."
  }'

PUT /api/users/profile

curl -X PUT https://your-homarr.com/api/users/profile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user-id",
    "name": "newusername",
    "email": "newemail@example.com"
  }'

DELETE /api/users/

curl -X DELETE https://your-homarr.com/api/users/user-id-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Examples

Complete User Setup

// Create user
await api.user.create.mutate({
  username: "teamlead",
  password: "secure-password-123",
  email: "teamlead@example.com",
  groupIds: ["managers-group-id"],
});

// Get the new user
const users = await api.user.search.query({ query: "teamlead" });
const newUser = users[0];

// Set preferences
await api.user.changeHomeBoards.mutate({
  userId: newUser.id,
  homeBoardId: "main-board-id",
  mobileHomeBoardId: "mobile-board-id",
});

await api.user.changeColorScheme.mutate({
  colorScheme: "dark",
});

Overview

tRPC API

WebSocket

Overview

Queries

getAll

selectable

search

getById

Mutations

initUser

register

create

setProfileImage

editProfile

changePassword

changeHomeBoards

changeSearchPreferences

changeColorScheme

changePingIconsEnabled

changeFirstDayOfWeek

delete

OpenAPI Endpoints

GET /api/users

GET /api/users/selectable

POST /api/users/search

GET /api/users/

POST /api/users

PUT /api/users/profileImage

PUT /api/users/profile

DELETE /api/users/

Examples

Complete User Setup

Build docs developers (and LLMs) love

Overview

tRPC API

WebSocket

Documentation Index

​Overview

​Queries

​getAll

​selectable

​search

​getById

​Mutations

​initUser

​register

​create

​setProfileImage

​editProfile

​changePassword

​changeHomeBoards

​changeSearchPreferences

​changeColorScheme

​changePingIconsEnabled

​changeFirstDayOfWeek

​delete

​OpenAPI Endpoints

​GET /api/users

​GET /api/users/selectable

​POST /api/users/search

​GET /api/users/

​POST /api/users

​PUT /api/users/profileImage

​PUT /api/users/profile

​DELETE /api/users/

​Examples

​Complete User Setup

Build docs developers (and LLMs) love

Overview

Queries

getAll

selectable

search

getById

Mutations

initUser

register

create

setProfileImage

editProfile

changePassword

changeHomeBoards

changeSearchPreferences

changeColorScheme

changePingIconsEnabled

changeFirstDayOfWeek

delete

OpenAPI Endpoints

GET /api/users

GET /api/users/selectable

POST /api/users/search

GET /api/users/

POST /api/users

PUT /api/users/profileImage

PUT /api/users/profile

DELETE /api/users/

Examples

Complete User Setup