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();
admin
Response:
Email verification timestamp
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,
});
If true, only returns users with credentials provider
search
Search users by name.
const users = await api.user.search.query({
query: "john",
limit: 10,
});
admin
getById
Get detailed user information.
const user = await api.user.getById.query({ userId: "user-id" });
admin (any user)
Response:
provider
'credentials' | 'oidc' | 'ldap'
Authentication provider
User’s default home board
First day of week (0 = Sunday, 1 = Monday)
Whether app ping icons are enabled
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: "[email protected]",
});
This endpoint is only available during initial onboarding. Once the first user is created, it becomes inaccessible.
register
Register a new user via invite.
await api.user.register.mutate({
username: "newuser",
password: "secure-password",
email: "[email protected]",
inviteId: "invite-id",
token: "invite-token",
});
FORBIDDEN - Invalid or expired inviteCONFLICT - Username already taken
create
Create a new user (admin only).
await api.user.create.mutate({
username: "newuser",
password: "secure-password",
email: "[email protected]",
groupIds: ["group-id-1", "group-id-2"],
});
admin
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...",
});
admin (any user)
Parameters:
Base64-encoded image data URI (max ~256KB) or null to remove
- 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: "[email protected]",
});
admin (any user)
Only users with credentials provider can change username and email. Users authenticated via OIDC/LDAP cannot modify these fields.
- 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",
});
Current password (required when changing own password)
- 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",
});
admin (any user)
Parameters:
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,
});
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
});
First day of week (0-6, where 0 is Sunday)
delete
Delete a user account.
await api.user.delete.mutate({ userId: "user-id" });
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": "[email protected]",
"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": "[email protected]"
}'
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: "[email protected]",
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",
});
