Skip to content

API request authorization

Getting the access token

Specify a JWT token in the HTTP Header in order for any Watcher API call to be executed. To get the token, use the corresponding request:

Example of the request to get the token:

curl -X POST -u user:password "http://localhost:80/watcher/client-api/v3/login"

In the response to this request, there are two parameters:

  • access_token is a JWT token for executing API calls. It has a limited validity period encoded in the token itself.
  • refresh_token is a long-lasting token that can be used to request a new access_token. When you implement your application, store the refresh_token, for example, in the database so that you can use it when needed.

Example of using access_token:

curl -X GET "http://localhost:80/watcher/client-api/v3/streams" \
    -H "Authorization: Bearer <access_token>" \

Refreshing the token without login and password

When the server returns HTTP 401 to a request with the access_token, use refresh_token from the /login response to request the new token like that:

curl -X POST "http://localhost:80/watcher/client-api/v3/login" \
-H "Authorization: Bearer <refresh_token>" \

This way the user does not have to enter the login and password again.

Authorization in API v2

The old API v2 offered three types of authorization:

  1. System x-vsaas-api-key from Watcher settings. It allows to execute any requests.

    curl -v -X GET -H 'x-vsaas-api-key: 7c75da8fb314183f1f825271898a3687' http://127.0.0.1/vsaas/api/v2/cameras

  2. x-vsaas-session returned in response to /vsaas/api/v2/auth/login request in the session parameter. This key allows requests within the logged in user permissions.

    curl -v -X GET -H 'x-vsaas-session: W98uOoiMFf46SyE78RjWIZjsaVM' http://127.0.0.1/vsaas/api/v2/auth/whoami

  3. User x-vsaas-api-key from user profile Use this key with x-vsaas-user: user name. It allows requests within the permissions of the specified user.

    curl -v -X GET -H 'x-vsaas-api-key: M8rT4KvfT3tZpCj34Qbk5CEt' -H 'x-vsaas-user: user1' http://127.0.0.1/vsaas/api/v2/cameras