Collection behavior

User and Group Management endpoints can return collections of users or groups.
These collection endpoints are stateless and can support filtering, sorting, and pagination.

Collection behavior defines how results are ordered, limited, and navigated when retrieving users or groups through the API.

Stateless collection APIs

All User and Group Management collection endpoints are stateless.

A stateless API can be requested directly at any time without creating or maintaining server-side query state. Each request fully defines the result through its request parameters.

Filtering, sorting, and pagination

When multiple collection operations are used together, they are always applied in the following order:

1. Filtering (search)
2. Sorting
3. Pagination

Filtering limits the result set, sorting defines the order of items, and pagination divides the result into pages. 

Ordering of returned items

The order in which items are returned is only defined when sorting is explicitly applied or documented.

If ordering is undefined:

• Clients must not assume items are returned in a stable or natural order.
• Consecutive requests can return items in different orders.
• Changes in backend implementation must not break correctly implemented clients.

Undefined ordering is valid API behavior.

Natural ordering is not guaranteed and should not be relied upon unless explicitly documented.

Sorting support

Sorting support varies between User Management endpoints.

Endpoints that return group members or memberships do not support sorting and return items in an undefined order.

The user view API only allows sorting on fields included in the response. Available sorting fields can therefore depend on permissions and client scope.

Sorting request parameter

Sortable collection endpoints accept the query parameter:

The parameter specifies the requested sorting order.

Format: <FIELD>[:<DIRECTION>][,<FIELD>[:<DIRECTION>]]

Where:

• FIELD is a supported sorting field identifier.
• DIRECTION can be:
  • asc — ascending order
  • desc — descending order

If no direction is specified, the server-defined default order is used.

Example:GET /fotoweb/api/users/?sortFields=username:desc

Multiple fields can be specified when supported by the endpoint: sortFields=licenseType,lastLoginDate:desc

Fields are applied in lexicographical order from left to right.

Sorting information in responses

Responses from sortable collection endpoints include a sorting object describing available sorting options and the actual order used.

Example:

{
  "sorting": {
    "key": {
      "fields": [
        {
          "fieldName": "username",
          "sortDirection": "desc"
        }
      ]
    },
    "allowedFields": [
      {
        "id": "id",
        "label": "ID",
        "reversible": true
      },
      {
        "id": "username",
        "label": "User Name",
        "reversible": true
      }
    ],
    "multipleFieldsAllowed": false
  }

sorting.key

Specifies the actual sorting order applied to the returned items. Clients should rely on this value to determine the current sorting state.

sorting.allowedFields

Lists the fields that can be used in the sortFields request parameter.

• id identifies the sorting field.
• label is a human-readable name suitable for user interfaces.
• reversible indicates whether the sorting direction can be changed.

A sorting field does not necessarily correspond directly to an attribute in returned items.

sorting.multipleFieldsAllowed

Indicates whether multiple comma-separated sorting fields can be specified.

If false, only a single sorting field can be used.

Behavior when sorting is not supported

If the response does not include a sorting attribute, or if its value is null, the endpoint does not support sorting, and item order is undefined unless otherwise documented.

Client implementation guidance

Clients should dynamically discover sorting capabilities using the API response.

Clients should:

• Read available sorting options from the sorting attribute.
• Construct sorting requests using supported fields only.
• Trust the response to determine the actual sorting order.

Clients should not rely on assumed or previously observed ordering.

Client-side sorting can be implemented only after retrieving the complete collection and is recommended only for small result sets.

Performance considerations

Sorting options are selectively exposed to ensure acceptable API performance.

Efficient sorting of large collections typically requires database-level execution and indexed fields. For this reason, not all fields can support sorting.

Pagination performance should remain predictable regardless of page position whenever possible.

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. The only properties that can be changed are the email address and the 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 Fotoware Veloz but used by non-interactive integrations as the request user. It is visible on-premises. It can be used as a regular user that allows logging in with a password, but this is not recommended anymore.

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 membership is implicit, meaning it is 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 Fotoware Veloz site SHOULD have a site owner.

The site owner has the following additional privileges:

• Set a new site owner (and resign as the 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 a single member or membership.
• 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 for 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.