web sdk users

Managing users and user groups

Security Center users are the accounts that people use to sign in 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

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	When true, the user is prompted to change their password on next sign-in.
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–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 groups this user belongs to.
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 set a password and PasswordLastModified to check when it was last changed.

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({password})

Note

The password must satisfy the Security Center password complexity policy and must not exceed 32 characters. If the password is too weak or too long, the request fails with SdkErrorCode: "InvalidValue".

To set a password expiration in days:

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

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.

To remove expiration:

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

Measurement system

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

Security level

The security level (1–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})

Note

SetDomain() and SetExternalUniqueId() can each be called only once for a user. A second call fails with CannotSetProperty. When ExternalUniqueId has not been set, it is omitted from the response entirely rather than returned as an empty string.

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

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

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}.

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:

Note

UserWatermarkingConfiguration is readable only when watermarking is enabled for that user or group.

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

The Web SDK response commonly includes these watermarking fields: 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).

Note

You can enable or disable watermarking through the Web SDK, but you cannot change watermark layout or content settings through documented Web SDK requests. 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 Partitions for the InsertIntoPartition and RemoveFromPartition 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 has a list of 645 privileges, each identified by 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 for all 645 privileges.

Note

For users, Privileges shows the privilege states defined directly on that user. Privileges inherited from user groups or system defaults can still appear as Undefined in this list.

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 only.
ApplyToChildrenPrivileges	Applies the state to the specified privilege and all of its sub-privileges.

Grant a privilege:

POST /entity?q=entity={user-guid},SetPrivilegeState(7902233c-5e84-4de1-ae6e-7803ddf42384,Granted,Default)

Deny a privilege and all its sub-privileges:

POST /entity?q=entity={user-guid},SetPrivilegeState(7902233c-5e84-4de1-ae6e-7803ddf42384,Denied,ApplyToChildrenPrivileges)

Reset to inherited:

POST /entity?q=entity={user-guid},SetPrivilegeState(7902233c-5e84-4de1-ae6e-7803ddf42384,Undefined,Default)

Checking whether a user has a privilege

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

Returns {"HasPrivilege": true} or {"HasPrivilege": false}. Accounts for both the user's direct privilege state and any inherited group state.

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

• Partitions
• Reference