Skip to main content
Documentation & User Guides | Fotoware

User Management API

  1. Last updated
  2. Save as PDF
Learn how to use the API to manage users and groups.

 

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:

  1. M is a direct member of G
  2. 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.

 

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
    Product version
    FotoWare Integrations and API
    Stage
    Final
  2. Tags
    1. groups
    2. integration
    3. users