Skip to content

User management API

You can use user management API requests to integrate Watcher with billing or to develop your own application/web interface for Watcher, etc. For example, if Provider creates Organizations, presets and users from the Watcher interface, then the billing will most likely need to request information about created users and which Organization(s) they are added to, user permissions assigned. If billing is a control system, implement the requests for creating, changing and deleting users as well as permissions assigning.

Please refer to Integration with existing billing system for details on cameras provisioning and billing integration. You can also find useful: Folder management API .

This section provides examples of API requests for managing users. Click here to see the full list of response and request parameters.

You should use one of the keys for the API request authorization. The examples in this section are given with the x-vsaas-session key: this means that the user on whose behalf the requests are made must have the rights to perform the corresponding actions. Please refer to API request authorization ways for details on the key types.

Creating a user in the Organization

If you have the list of users in csv, import all users at once as described in User import API.

If you are adding one user at a time, use this query

POST YOUR_WATCHER_URL/vsaas/api/v2/users?trace=sql

Required parameters:

  • login (string) — the username to log into the Watcher app/web interface.
  • password (string) — user password

Optional parameters for settings on the Parameters tab in the interface (see Managing users and their permissions for details):

  • organization_id (integer) — ID of the Organization to add the user to. If not specified, the user will be added to the Default Organization. You can add the user into one Organization at creation. If you want to add the user to several Organizations, use the adding user request shown below after creation.
  • can_edit_organizations (boolean) — true if the user can edit Organizations, default is false.
  • can_view_organizations (boolean) — true if the user can view Organizations, default is false.
  • enabled (boolean) — whether the user is active or not, default is true
  • is_admin (boolean) — whether the user is Watcher Administrator, default is false.
  • readonly (boolean) — enables read-only mode for the user, default is false.
  • max_sessions (integer) — maximum number of sessions.
  • can_edit_settings (boolean) — whether the user can manage Watcher settings (on the Settings page), default is false. There is no corresponding setting in the interface.

Other optional parameters:

  • apikey (string) — user's API key which is one of the ways to authorize an API request. See API request authorization ways for details.
  • locale (string) — interface language
  • name (string) — user name
  • note (string) — note
  • notification_email (string (email)) — user's e-mail address
  • phone (string) — user's phone number

Example

curl --request POST \
--url 'http://localhost/vsaas/api/v2/users?trace=sql' \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"login": "test",
"password": "test",
"organization_id": 1
}'

The response will contain all the parameters of the created user.

Please note that the Organizations array is returned in the response.

{
    "apikey": null,
    "id": 17,
    "can_view_organizations": false,
    "max_sessions": null,
    "name": null,
    "locale": "",
    "login": "test",
    "external_id": null,
    "organizations": [
        1
    ],
    "readonly": false,
    "can_edit_organizations": false,
    "note": null,
    "is_admin": false,
    "authorized_ip": null,
    "phone": null,
    "notification_email": null,
    "monitoring": false,
    "enabled": true,
    "can_edit_settings": false,
    "domain_id": 1
}

Getting a list of users in the Organization

Use the following request to get the list of users in the Organization

GET YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/users

Example

curl --request GET \
--url http://localhost/vsaas/api/v2/organizations/1/users \
--header 'x-vsaas-session: <vsaas_session>'

The response will contain some general parameters of users and their permissions within the Organization.

[
    {
        "notification_email": null,
        "can_edit_organization_users": true,
        "login": "Subscriber 1",
        "can_edit_organization_plists": true,
        "can_view_organization_stats": true,
        "can_edit_organization_cameras": true,
        "can_view_organization_plists": true,
        "user_id": 14,
        "folders_permissions": [
            {
                "folder_id": 1,
                "can_view_dvr": true,
                "dvr_depth_limit": 365,
                "can_use_ptz": false,
                "can_use_actions": false
            },
            {
                "folder_id": 25,
                "can_view_dvr": false,
                "dvr_depth_limit": null,
                "can_use_ptz": false,
                "can_use_actions": false
            }
        ]
    },
    {
        "notification_email": null,
        "can_edit_organization_users": false,
        "login": "Subscriber 2",
        "can_edit_organization_plists": false,
        "can_view_organization_stats": false,
        "can_edit_organization_cameras": false,
        "can_view_organization_plists": false,
        "user_id": 24,
        "folders_permissions": []
    }
]

Adding the user to the Organization

Use the following request to add an existing user to the Organization

POST YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/users

Request parameters:

  • user_id (integer) — required parameter, identifier of the added user
  • login (string) — username
  • notification_email (string) — user's e-mail address
  • can_view_organization_plists (boolean) — permissions to view the person lists within Organization
  • can_edit_organization_plists (boolean) — permissions to edit the person lists within Organization
  • can_edit_organization_users (boolean) — permissions to edit users
  • can_edit_organization_cameras (boolean) — permissions to edit cameras within the Organization
  • can_view_organization_stats (boolean) — permissions to view statistics
  • folders_permissions (array) — a list of the Organization's folders to which the user has access

Example

curl --request POST \
--url http://localhost/vsaas/api/v2/organizations/1/users \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data ' {
"user_id": 2,
"can_edit_organization_cameras": true
}'

The response will contain some general parameters of the user and their permissions within the Organization.

{
    "can_edit_organization_plists": false,
    "can_edit_organization_users": false,
    "user_id": 2,
    "notification_email": null,
    "can_edit_organization_cameras": true,
    "can_view_organization_stats": false,
    "folders_permissions": [],
    "can_view_organization_plists": false,
    "login": "test"
}

Getting permissions of one user

Use the following request to get the user's permissions

GET YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/users/(user ID)

Example

curl --request GET \
--url http://localhost/vsaas/api/v2/organizations/1/users/2/ \
--header 'x-vsaas-session: <vsaas_session>'

The response will contain some general parameters of the user and their permissions within the Organization similar to the example above.

Changing the user's permissions within the Organization

Use the following request to change the user's permissions within the Organization

PUT YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/users/(user ID)

The request parameters are the same as when adding an existing user to the Organization. You can include only those parameters that need to be changed to the request body.

Example

curl --request PUT \
--url http://localhost/vsaas/api/v2/organizations/1/users/2/ \
--header 'content-type: application/json' \
--header 'x-vsaas-session: <vsaas_session>' \
--data '{
"can_view_organization_stats": true,
"can_edit_organization_users": true,
"can_edit_organization_cameras": true
}'

The response will contain some general parameters of the user and their permissions within the Organization similar to the example above.

Deleting the user from the Organization

Use the following request to delete the user from the Organization

DELETE YOUR_WATCHER_URL/vsaas/api/v2/organizations/(organization ID)/users/(user ID)

curl --request DELETE \
--url http://localhost/vsaas/api/v2/organizations/1/users/2/ \
--header 'x-vsaas-session: <vsaas_session>'

If the deletion is successful, Watcher responds with {"success":true}