web sdk users

Managing users and user groups

Security Center users are the accounts that people use to log on to Security Desk, Config Tool, and other client applications. User groups hold users and can be assigned privileges collectively. Users inherit the privilege state of any group they belong to. A privilege set directly on a user overrides what would otherwise be inherited from the group.

Creating users and user groups

To create a user:

POST /entity?q=entity=NewEntity(User),Name=jsmith,FirstName=Jane,LastName=Smith,Guid

To create a user group:

POST /entity?q=entity=NewEntity(UserGroup),Name=VideoOperators,Guid

Both requests return the new entity's GUID in Rsp.Result.Guid.

User properties

Use these properties and methods to read and update individual user accounts.

Reading user properties

GET /entity?q=entity={user-guid},Name,FirstName,LastName,Description,EmailAddress,UserStatus,ExpirationMode,ExpirationDate,ExpirationDuration,ExpirationIsInherited,NeedChangePassword,PasswordExpiration,PasswordLastModified,DefaultMeasurementSystem,SecurityLevel,IsSecurityLevelInherited,ArchiveViewingLimitation,IsArchiveViewingLimitationInherited,Domain,ActiveDirectoryDomainName,ExternalUniqueId,ExternalSystemUserStatus,IsAdministrator,IsSystemAdministratorUser,UserGroups,PtzPriorities

Property	Type	Access	Description
Name	string	Read/Write	The user's login name.
FirstName	string	Read/Write	The user's first name.
LastName	string	Read/Write	The user's last name.
Description	string	Read/Write	Optional description for the user account.
EmailAddress	string	Read/Write	The user's email address.
UserStatus	UserStatus	Read/Write	Whether the account is active. Values: Activated, Deactivated.
ExpirationMode	UserExpirationMode	Read/Write	How the account expires. Values: DontExpire, Expiring, WhenNotUsed.
ExpirationDate	DateTime	Read/Write	The date the account expires. Set when ExpirationMode is Expiring.
ExpirationDuration	int	Read/Write	Days of inactivity before the account expires. Set when ExpirationMode is WhenNotUsed.
ExpirationIsInherited	bool	Read	Whether the expiration settings are inherited from the user group.
NeedChangePassword	bool	Read/Write	Whether the user is prompted to change their password on next logon.
PasswordExpiration	int	Read/Write	Number of days before the password expires. Supported range: 0 to 999. 0 means the password does not expire.
PasswordLastModified	DateTime	Read	The last time the password was changed.
DefaultMeasurementSystem	MeasurementSystemType	Read/Write	The measurement system for the user. Values: Metric, Imperial.
SecurityLevel	int	Read/Write	The user's security level (1 to 254), where 1 is the highest clearance and 254 is the lowest. Controls access to privacy-protected camera video.
IsSecurityLevelInherited	bool	Read/Write	When true, the security level is inherited from the user group. Set to false to apply a custom security level.
ArchiveViewingLimitation	TimeSpan	Read/Write	How far back the user can view recorded video. Format: d.hh:mm:ss. 00:00:00 means no restriction.
IsArchiveViewingLimitationInherited	bool	Read/Write	When true, the archive viewing limitation is inherited from the user group. Set to false to apply a custom limit.
Domain	string	Read	The domain value associated with the user. Set it once with SetDomain().
ActiveDirectoryDomainName	string	Read	Returns the same domain value exposed by Domain.
ExternalUniqueId	string	Read	An external identity system identifier. Set it once with SetExternalUniqueId().
ExternalSystemUserStatus	UserStatus	Read	The user's status as reported by the external identity system.
IsAdministrator	bool	Read	Whether this is the system administrator account.
IsSystemAdministratorUser	bool	Read	Whether this is the built-in system administrator user.
UserGroups	Guid[]	Read	The GUIDs of the user's direct parent groups.
PtzPriorities	array	Read	PTZ camera priority entries assigned to this user. Each entry contains a camera GUID and a priority number.

Note

Passwords cannot be read. Use SetPassword() to submit a new password value and PasswordLastModified to read the timestamp currently stored for that account.

Setting account status

POST /entity?q=entity={user-guid},UserStatus=Deactivated
POST /entity?q=entity={user-guid},UserStatus=Activated

Setting a password

POST /entity?q=entity={user-guid},SetPassword({url-encoded-password})

Note

Security Center enforces the password policy configured on the system. The Web SDK does not expose the current password policy settings, such as minimum length or character requirements. Passwords can be up to 32 characters. URL-encode reserved characters in the password value, and handle Rsp.Status: "Fail" from SetPassword(...) when a password fails the policy or length check.

To set a password expiration in days:

POST /entity?q=entity={user-guid},PasswordExpiration=90

Accepted range is 0 to 999. Values outside that range fail.

Setting account expiration

To expire the account on a fixed date:

POST /entity?q=entity={user-guid},ExpirationMode=Expiring,ExpirationDate=2027-01-01T00:00:00Z

To expire the account after a period of inactivity:

POST /entity?q=entity={user-guid},ExpirationMode=WhenNotUsed,ExpirationDuration=30

ExpirationDuration is in days. When set, ExpirationDate reflects the calculated expiry date.

Note

ExpirationDate must be in the future and is stored as UTC. Values without an explicit timezone (Z or ±hh:mm) are assumed to be UTC as-written, so include the offset when entering a local time. ExpirationDuration must be 0 or greater.

To remove expiration:

POST /entity?q=entity={user-guid},ExpirationMode=DontExpire

Setting ExpirationMode=DontExpire disables expiration, but the stored ExpirationDate and ExpirationDuration values can remain populated.

Measurement system

POST /entity?q=entity={user-guid},DefaultMeasurementSystem=Imperial
POST /entity?q=entity={user-guid},DefaultMeasurementSystem=Metric

Security level

The security level (1 to 254) controls access to privacy-protected camera video. 1 is the highest clearance and 254 is the lowest. When a camera is blocked at a specific blocking level, users with a numerically higher security level than that blocking level cannot view the blocked video. A user's effective security level for a specific camera can be read using GetSecurityLevelForCamera.

POST /entity?q=entity={user-guid},IsSecurityLevelInherited=false,SecurityLevel=5

GET /entity?q=entity={user-guid},GetSecurityLevelForCamera({camera-guid})

To inherit the security level from the user group:

POST /entity?q=entity={user-guid},IsSecurityLevelInherited=true

Archive viewing limitation

Restricts how far back a user can view recorded video. Use TimeSpan format d.hh:mm:ss. 00:00:00 means no restriction.

POST /entity?q=entity={user-guid},ArchiveViewingLimitation=7.00:00:00,IsArchiveViewingLimitationInherited=false

To inherit from the user group:

POST /entity?q=entity={user-guid},IsArchiveViewingLimitationInherited=true

Domain and external identity

To associate the user with a Windows or Active Directory domain:

POST /entity?q=entity={user-guid},SetDomain({domain-name})

To set an external identity system identifier:

POST /entity?q=entity={user-guid},SetExternalUniqueId({external-id})

SetDomain() and SetExternalUniqueId() can be set only once. Later calls fail and leave the stored value unchanged.

PTZ priorities

PTZ priorities determine which user takes control of a PTZ camera when multiple users try to operate it simultaneously. A user with a higher priority number takes precedence. Each entry contains the GUID of a camera and the user's priority for that camera. PTZ priorities can be set on both users and user groups.

To read the current PTZ priorities:

GET /entity?q=entity={user-or-group-guid},PtzPriorities

To assign a PTZ priority for a specific camera:

POST /entity?q=entity={user-or-group-guid},AddPtzPriority(PtzPriority({camera-guid},{priority}))

To remove a PTZ priority entry:

POST /entity?q=entity={user-or-group-guid},RemovePtzPriority(PtzPriority({camera-guid},{priority}))

Deleting users and user groups

DELETE /entity/{user-guid}
DELETE /entity/{group-guid}

User group properties

User groups expose many of the same account controls, but they apply those settings to members who inherit them.

Reading user group properties

GET /entity?q=entity={group-guid},Name,Description,EmailAddress,ExternalUniqueId,ExpirationMode,ExpirationDate,ExpirationDuration,ExpirationIsInherited,SecurityLevel,IsSecurityLevelInherited,ArchiveViewingLimitation,IsArchiveViewingLimitationInherited,IsSystemAdministratorsUserGroup,Children,UserGroups

Property	Type	Access	Description
Name	string	Read/Write	The group name.
Description	string	Read/Write	Optional description for the group.
EmailAddress	string	Read/Write	The group's email address.
ExternalUniqueId	string	Read/Write	An external identity system identifier for the group.
ExpirationMode	UserExpirationMode	Read/Write	How group membership expires. Values: DontExpire, Expiring, WhenNotUsed.
ExpirationDate	DateTime	Read/Write	The date group membership expires. Set when ExpirationMode is Expiring.
ExpirationDuration	int	Read/Write	Days of inactivity before membership expires. Set when ExpirationMode is WhenNotUsed.
ExpirationIsInherited	bool	Read	Whether expiration is inherited from a parent group.
SecurityLevel	int	Read/Write	The group's security level. Applies to all members who inherit it.
IsSecurityLevelInherited	bool	Read/Write	Whether the security level is inherited from a parent group.
ArchiveViewingLimitation	TimeSpan	Read/Write	Archive viewing limit applied to group members.
IsArchiveViewingLimitationInherited	bool	Read/Write	Whether the archive viewing limit is inherited from a parent group.
IsSystemAdministratorsUserGroup	bool	Read	Whether this is the built-in Administrators group.
Children	Guid[]	Read	The GUIDs of all direct members, including both users and nested child groups. Use AddChild(...) and RemoveChild(...) to manage membership.
UserGroups	Guid[]	Read	The GUIDs of parent groups this group belongs to.

Security level

POST /entity?q=entity={group-guid},IsSecurityLevelInherited=false,SecurityLevel=10

To inherit the security level from a parent group:

POST /entity?q=entity={group-guid},IsSecurityLevelInherited=true

Archive viewing limitation

POST /entity?q=entity={group-guid},ArchiveViewingLimitation=7.00:00:00,IsArchiveViewingLimitationInherited=false

To inherit from a parent group:

POST /entity?q=entity={group-guid},IsArchiveViewingLimitationInherited=true

Listing and searching users and groups

Use UserReport and UserGroupReport to find users and groups. Both reports support ReturnFields to limit the returned properties. For more information, see Referencing entities.

List all users:

GET /report/UserReport?q=PageSize=100,ReturnFields@Name

Filter by account status:

GET /report/UserReport?q=Status@Activated,PageSize=100,ReturnFields@Name

Search by name, first name, last name, or email:

GET /report/UserReport?q=Name=smith,NameSearchMode=Contains,PageSize=50,ReturnFields@Name
GET /report/UserReport?q=FirstName=jane,FirstNameSearchMode=Contains,PageSize=50,ReturnFields@Name
GET /report/UserReport?q=LastName=smith,LastNameSearchMode=Contains,PageSize=50,ReturnFields@Name
GET /report/UserReport?q=Email=smith,EmailSearchMode=Contains,PageSize=50,ReturnFields@Name

Filter users by group membership:

GET /report/UserReport?q=UserGroupIds@{group-guid},PageSize=100,ReturnFields@Name

To include users from nested child groups, add GroupRecursive=true:

GET /report/UserReport?q=UserGroupIds@{group-guid},GroupRecursive=true,PageSize=100,ReturnFields@Name

Filter users by security level range:

GET /report/UserReport?q=SecurityLevelLowerBound=1,SecurityLevelUpperBound=10,PageSize=100,ReturnFields@Name

List all user groups:

GET /report/UserGroupReport?q=PageSize=100,ReturnFields@Name

Search user groups by name:

GET /report/UserGroupReport?q=Name=operator,NameSearchMode=Contains,PageSize=50,ReturnFields@Name

Managing group membership

Use these methods to add or remove direct members and to build nested group structures.

Adding and removing members

To add a user or child group to a group:

POST /entity?q=entity={group-guid},AddChild({member-guid})

To remove a user or child group:

POST /entity?q=entity={group-guid},RemoveChild({member-guid})

To check whether a specific entity is a member:

GET /entity?q=entity={group-guid},IsMember({entity-guid})

Returns {"IsMember": true} or {"IsMember": false}.

IsMember(...) follows nested group membership. If a user belongs to a child group that is itself a member of the queried parent group, IsMember(...) on the parent group returns true.

Nesting groups

User groups can contain other user groups as children. Members of a child group inherit the parent group's privileges.

To add a child group:

POST /entity?q=entity={parent-group-guid},AddChild({child-group-guid})

To remove a child group:

POST /entity?q=entity={parent-group-guid},RemoveChild({child-group-guid})

Video watermarking

Video watermarking overlays user information (username, camera name, workstation) on live and playback video. Watermarking can be configured on both users and user groups. Users inherit watermarking settings from their group by default.

To apply custom watermarking settings for a user or group, first disable inheritance:

POST /entity?q=entity={user-or-group-guid},IsUserWatermarkingConfigurationInherited=false

Then enable watermarking:

POST /entity?q=entity={user-or-group-guid},EnableUserWatermarking()

To disable watermarking:

POST /entity?q=entity={user-or-group-guid},DisableUserWatermarking()

To read the current watermarking configuration, include UserWatermarkingConfiguration in the query only when watermarking is enabled for that user or group. If watermarking is disabled, request only the IsUserWatermarkingConfigurationEnabled flag.

GET /entity?q=entity={user-or-group-guid},IsUserWatermarkingConfigurationEnabled,UserWatermarkingConfiguration

The Web SDK response can include fields such as Opacity (1 to 100), Size (1 to 100), IncludeUsername, IncludeCameraName, IncludeWorkstation, OverlayType (Single, Mosaic), MosaicOrientation (Horizontal, Diagonal), and OverlayPosition (TopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter, BottomRight). Other fields are also available, including AppearsInLive, AppearsInPlayback, AppearsInExports, AutoScale, IncludeCustomText, CustomText, Color, and OutlineColor.

Note

The Web SDK can enable or disable watermarking, but overlay settings remain read-only. Use Config Tool to change overlay settings such as opacity, size, and content.

Partitions

Users and user groups support partition membership. To add a user or group to a partition, see Working with partitions for the AddMember and RemoveMember operations, which apply to all entity types including users and groups.

The UserGroups property on a user returns the GUIDs of the user's direct parent groups. It does not include parent groups reached through nested group membership.

Privileges

Privileges control what a user or group is allowed to do in Security Center. Every user and group exposes a privilege list. Each entry has a stable GUID and a state.

Privilege states

State	Meaning
Undefined	The privilege inherits its state from the user's group or from the system default.
Granted	The privilege is explicitly allowed, overriding any inherited state.
Denied	The privilege is explicitly blocked, overriding any inherited state.

Reading privileges

GET /entity?q=entity={user-or-group-guid},Privileges

Returns an array of objects with PrivilegeGuid and State fields.

Note

Privileges shows the direct privilege states defined on the user or group. It does not show the final resolved privilege state after inheritance is applied, so it can differ from what Config Tool shows.

Setting a privilege

POST /entity?q=entity={user-or-group-guid},SetPrivilegeState({privilege-guid},{state},{behavior})

{state} is one of Granted, Denied, or Undefined.

{behavior} controls propagation:

Value	Effect
Default	Applies the state to the specified privilege.
ApplyToChildrenPrivileges	Applies the state to the specified privilege and all of its sub-privileges.

Grant a privilege:

POST /entity?q=entity={user-guid},SetPrivilegeState({privilege-guid},Granted,Default)

Deny a privilege and all its sub-privileges:

POST /entity?q=entity={user-guid},SetPrivilegeState({privilege-guid},Denied,ApplyToChildrenPrivileges)

Reset to inherited:

POST /entity?q=entity={user-guid},SetPrivilegeState({privilege-guid},Undefined,Default)

If you change privileges on the same user identity that is currently authenticated to the Web SDK, do not assume the current session immediately reflects the change. Web SDK sessions are reused for the same credentials, Application ID, and Web SDK instance.

You cannot change privileges on the built-in administrator user or the built-in Administrators group. SetPrivilegeState(...) fails for those built-in accounts.

Checking whether a user has a privilege

GET /entity?q=entity={user-guid},HasPrivilege({privilege-guid})

Returns {"HasPrivilege": true} or {"HasPrivilege": false}. This does not report the user's direct granted or denied state from Privileges. Use Privileges to read the direct state defined on the user or group.

Checking whether a user can see an entity

GET /entity?q=entity={user-guid},HasAccess({entity-guid})

Returns {"HasAccess": true} or {"HasAccess": false}. This check covers partition visibility: a user without access to the entity's partition will return false.

See also

• The /entity endpoint: The /entity endpoint and shared q= query syntax.
• Reference: Well-known GUIDs, card format identifiers, and enumerations.