User management API¶
A user has an account in a domain and can belong to several organizations. Permissions are assigned separately for the domain, organizations and folders. All examples use API v3 authentication.
Create a user in an organization¶
For Client API, specify an organization whose users you may manage:
POST /watcher/client-api/v3/users
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "resident-example",
"fullname": "Irina Smirnova",
"password": "ExamplePassword",
"email": "resident@example.com",
"organization_id": 7,
"access_level": "generic",
"locale": "ru"
}
Save id from the response. name is the login, fullname is the display name and email is the notification address. Send the password in password. If the login is omitted, Watcher generates it; set it explicitly for an integration.
If organization_id is omitted in Client API, Watcher selects the first organization for which the caller has explicit user management permission, or returns a validation error. Specify the organization explicitly. The user count limit is checked during creation.
Create an ordinary user with access_level: "generic". To assign a domain administrator, send a separate request with the saved id:
PUT /watcher/client-api/v3/users/15
Authorization: Bearer <token>
Content-Type: application/json
{"access_level":"domain_admin"}
A Watcher administrator, or an existing administrator of the target domain who can access the user being changed, can assign this role. Sending domain_admin in POST /users alone does not assign the role. Check access_level in the PUT response.
admin grants Watcher administrator permissions; only a Watcher administrator can assign it. generic means an ordinary user. Organization and folder permissions are assigned separately.
Billing integrations with a system account can use POST /watcher/admin-api/v3/users. If the organization is omitted in Admin API, the user is added to the target domain's default organization. With an explicit organization_id, even Admin API checks permission to manage that organization's users. See the registration sequence in billing integration.
List organization users¶
GET /watcher/client-api/v3/organizations/7/users?limit=100
Authorization: Bearer <token>
The request requires permission to manage the organization's users. Process the users array and next cursor; pass the latter as cursor to continue.
Domain accounts are available through GET /watcher/client-api/v3/users within the caller's permissions. Admin API provides the administrative list /watcher/admin-api/v3/users.
Add a user to an organization¶
Create the account first, then add it by ID:
PUT /watcher/client-api/v3/organizations/7/users/15
Authorization: Bearer <token>
Content-Type: application/json
{"can_edit_users": false, "can_edit_streams": false, "can_view_streams": false}
If membership does not exist, PUT creates it. Permission fields are placed directly in the request body. Main fields:
- can_edit_users — manage organization users.
- can_edit_streams — manage organization cameras.
- can_view_streams — access all organization cameras.
- can_view_stats — view statistics.
- can_view_persons_lists — view person lists.
- can_edit_persons_lists — edit person lists.
- nvrs — NVR permissions:
{"can_view":true,"can_edit":false}.
can_edit_streams also grants camera viewing. For access to selected cameras only, leave organization-wide viewing disabled and assign folder permissions. The sequence for creating a user, obtaining folder_id, granting and revoking access is in the shared camera example.
Get a user's permissions¶
GET /watcher/client-api/v3/organizations/7/users/15
Authorization: Bearer <token>
The response describes the user and their organization permissions. It reflects effective permissions, including ownership: a returned value can differ from the flag you sent.
Change a user's organization permissions¶
Use the same PUT /organizations/7/users/15 with the required fields. Folder permissions use a separate request:
PUT /watcher/client-api/v3/organizations/7/folders/12/users/15
Authorization: Bearer <token>
Content-Type: application/json
{"can_view":true,"can_view_dvr":true,"dvr_depth_limit":0,"can_use_ptz":false}
Changing folder permissions requires camera management permission. Permissions also apply to subfolders. can_view permits live video, can_view_dvr permits archive playback; dvr_depth_limit limits access depth in seconds, and 0 removes that limit. can_use_ptz permits PTZ control.
Update account details¶
Update general account details through PUT /watcher/client-api/v3/users/{user_id} or its administrative counterpart. Send disabled: true to disable the account and disabled: false to enable it. Change a password with password; an administrator does not need a separate password change request. Disabling the account deletes its sessions; changing its password from another account also terminates the target user's sessions.
A user with readonly: true cannot send write requests regardless of other permissions.
Remove a user from an organization¶
DELETE /watcher/client-api/v3/organizations/7/users/15
Authorization: Bearer <token>
The request removes membership, organization permissions and folder permissions in this organization. The account remains. Removing the owner requires additional authority: the owner themselves or a user permitted to manage domain organizations can send the request.
For complete account deletion, an administrator uses DELETE /watcher/admin-api/v3/users/15. Successful deletion returns 204.