Table of Contents

Features Data model Memberships Built-in users Built-in groups Site owner Classification Special endpoints Membership relations Password management

User Management API

Learn how to use the API to manage users and groups.

02. April 2025

Table of Contents

Features Data model Memberships Built-in users Built-in groups Site owner Classification Special endpoints Membership relations Password management

Note: The User Management API and this documentation are currently in beta state. You are welcome to test both and give us feedback.

The User Management API is for querying and managing users and groups in FotoWeb. It allows API clients to programmatically add and modify users and groups and extract information about them. For example, customers connected to an authentication service can automatically remove employees from FotoWeb users when they leave the organization.

This is an administrative API and is only available when server-to-server authentication is used. Impersonated users and guests do not have access to users and groups, not even read access.

The API endpoint URLs are described in Features, and you can find them at Fotoware API.

Note:

The site owner cannot be set, modified, or deleted.
User streetAddress property is only exposed as an array and is limited to 4 lines.

Features

With the User Management API, API clients can do the following:

Groups	Users
Get group by ID	Get user by ID
Update a group	Update a user
Delete a group	Delete a user
Get all groups on the site	Get all users on the site
Create a new group	Create a new user
Count all groups on the site	Count all users on the site
Get all external IDs of a group	Delete the password of a user
Delete all external IDs of a group	Get all external IDs of a user
Delete the external ID of a group from a provider	Delete all external IDs of a user
Get all custom properties of a group	Delete the external ID of a user from a provider
Delete all custom properties of a group	Get all custom properties of a user
Delete a custom property of a group	Delete all custom properties of a user
Get all groups that the group is a direct number of	Delete a custom property of a user
Set the groups that the group is a direct number of	Get all groups that the user is a direct member of
Add the group to one or more groups	Set the groups that the user is a direct member of
Remove the group from all groups	Add the user to one or more groups
Count all groups that the group is a direct member of	Remove the user from all groups
Remove the group from a single group	Count all groups that the user is a direct member of
Get all distinct groups that the group is a direct or indirect member of	Remove the user from a single group
Count all distinct groups that the group is a direct or indirect member of	Get all distinct groups that the user is a direct or indirect member of
Get all users that are direct members of the given group	Count all distinct groups that the user is a direct or indirect member of
Replace all users that are direct members of a group	Enable or disable user
Add users to the given group
Remove all users from the given group
Count all users that are direct members of the given group
Get all users that are direct or indirect members of the given group
Count all users that are direct or indirect members of the given group
Get all groups that are direct members of the given group
Replace all groups that are direct members of a group
Add groups to the given group
Remove all groups from the given group
Count all groups that are direct members of the given group
Get all groups that are direct or indirect members of the given group
Count all groups that are direct or indirect members of the given group
Replace all direct members of a group
Add users to the given group
Remove all members from the given group
Remove a user from the given group
Remove a group from the given group

Data model

The following data is stored for each FotoWeb site:

A user - a user account and all associated information (for example, username, email, full name, address, password hash, SSO external IDs, license, and custom properties).
A group - a collection of users or other groups, which are called members of the group. Each group has a unique group ID, a unique group name, and other properties, such as permissions that are assigned to users.
A membership - a relation between a user and a group or between two groups.

Each user and group has a numeric ID (or simple ID), which is an integer number that is unique on any given site. It is unique on the server (and in the server’s database) with the site or tenant ID (site name).

Memberships

Each group has a set of direct members. A direct member can be either a group or a user.

Since groups can be members of groups and can themselves have members, it is implied that each group has indirect members, which are either direct or indirect members of its direct member groups.

Likewise, each user and each group can be a direct member of one or more groups. The group that a user or group is a direct member of is called a direct membership. Each direct membership (group) can itself be a direct or indirect member of other groups. These are called indirect memberships.

Example: A user or group M is an indirect member of group G if at least one of the following is true:

M is a direct member of G
M is a direct member of at least one group, G, which is an indirect member of G.

Each entry in the membership collection is a document with the following properties:

Site name
Membership type (user or group)
ID of member
ID of group

Built-in users

The following users are built-in users and always exist:

The guest user is the user with ID 15000 and username Guest. Its only property that can be changed is whether it is enabled or not.
The built-in administrator is the user with ID 15001 and username Administrator. Its only properties that can be changed are email address and password (hash).

The guest user is used for anonymous guest access and also symbolizes this in access lists.

The built-in administrator is hidden in SaaS but used by non-interactive integrations as the request user. It is visible on-premises. It may be used as a regular user that allows logging in with a password, but this is not recommended any more.

Built-in users cannot be deleted.

Built-in groups

The following groups are built-in groups and always exist:

The everyone group is the group with ID 10000 and the name Everyone. It implicitly contains all users, including the guest user.
The registered users group is the group with ID 10001 and the name Registered Users It implicitly contains all users, NOT including the guest user.

These groups are read-only. They cannot be members of other groups, and their members are implicit, which means they are not stored in the database. They are meant to be used in access lists.

Built-in groups cannot be deleted.

Site owner

The site owner is a regular user designated as the site owner.

Each site can have no site owner or exactly one site owner. Each SaaS site SHOULD have a site owner.

The site owner has the following additional privileges:

Set a new site owner (and resign as site owner itself)
All privileges of any user with Manage Users & Security permission
Additional privileges, such as SaaS subscription management

Classification

Read-only properties: isGuest, isAdministrator, isEveryone, isRegisteredUsers. If any of these is true, then another read-only property, isBuiltin, is also true.

The read-only property canEditwill be false in certain cases, for example, for the site owner if the request user is not the site owner and for built-in groups.

Special endpoints

For both users and groups, there are separate endpoints for managing properties and for managing external IDs.
For users, there are separate endpoints for changing or deleting the password.
There is no bulk change API for users and groups.

Membership relations

There are endpoints for adding one or multiple members or memberships and for deleting all or single members or memberships.
Memberships can no longer be edited using the regular update endpoints.
The regular GET endpoints no longer return members and memberships. These must always be requested separately.

Password management

A read-only property hasPassword is returned, specifying whether a user has a password.
Setting a new password on a user does NOT automatically set ForcePasswordChange to false.
Setting or removing a password does not automatically log users out of all sessions and applications.