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.
- The site owner cannot be set, modified, or deleted.
streetAddressproperty is only exposed as an array and is limited to 4 lines.
With the User Management API, API clients can do the following:
|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|
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).
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
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.
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 UsersIt 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.
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
isRegisteredUsers. If any of these is
true, then another read-only property,
isBuiltin, is also
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.
- 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.
- 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.
- A read-only property
hasPasswordis returned, specifying whether a user has a password.
- Setting a new password on a user does NOT automatically set
- Setting or removing a password does not automatically log users out of all sessions and applications.