API Authentication

Last modified: Thursday July 03, 2025.

All requests to the API require an authentication cookie.

Add an authentication user

The cookie request requires authentication with a username and password.

You can use any username and password for a user of the deployment, however, it is recommended you create a bespoke user, role, and user group to authenticate the calls for each API integration.

• Give the authentication user only the necessary permissions required for your integration, such as Arm/disarm alarm zones, View live video, Share video, and so on.
• Do not hard-code the username and password of the user. Either read them from a configuration file, or prompt the user for credentials.
• For more information on users, roles, and permissions, see Manage Protect users.

Request an authentication cookie

You need to generate an authentication cookie to pass with your API requests.

• The cookie is obtained by sending an HTTP POST request to:
  https://<deployment name>.<region>.alta.avigilon.com/api/v1/dologin
• The body must include the JSON: {"username":"<username>","password":"<password>"}
• The username and password are the email and password used by a user to log into the platform.
• For best practice, use a bespoke user account. See Add an authentication user above.
• The authentication cookie is in the request response.

Get an authentication cookie from a Windows Command Prompt

1. On a Windows PC, open a Command Prompt.

2. Enter:

   curl -v ^
-H "Content-Type: application/json" ^
-d "{\"username\":\"<username>\",\"password\":\"<password>\"}" ^
https://<deployment name>.<region>.alta.avigilon.com/api/v1/dologin

   1. Leave out the ^ carets if you enter the command in one line.
   2. Escape the internal double quotes around the JSON name/value pairs with backslashes: \"

3. You can see the cookie in the response, for example: Set-Cookie: va=eyJzdWIiOiTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoIxMjM0NxNTE2MjM5MDIyLCJleHAiOjE2NDU3NjY0MDB9

Store and use an authentication cookie from a Windows Command Prompt

You can store the cookie locally and use it to authenticate subsequent command prompt or scripted API requests:

1. On a Windows PC, run a Command Prompt from the folder where you want to store the cookie.

   1. To do this quickly, click the blank space next to the required folder's path in the Windows Explorer address bar and enter cmd.

2. Enter:

   curl -v ^
-c cookies.txt ^
-H "Content-Type: application/json" ^
-d "{\"username\":\"<username>\",\"password\":\"<password>\"}" ^
https://<deployment name>.<region>.alta.avigilon.com/api/v1/dologin

   1. Leave out the ^ carets if you enter the command in one line.
   2. Escape the internal double quotes around the JSON name/value pairs with backslashes: \"

3. The response shows that the cookie is saved: Added Cookie: va=<your authentication cookie>

4. Use the -b option in subsequent requests to use the stored cookie for authentication. For example, to return a list of zones, enter:

   curl -b cookies.txt ^
https://<deployment name>.<region>.alta.avigilon.com/api/v1/alarmZones

Get an authentication cookie using Postman

1. Download and install Postman.
2. Click New and select HTTP.
3. In the address bar, set the method to POST and enter the authentication URL for the deployment: https://<deployment name>.<region>.alta.avigilon.com/api/v1/dologin
4. Open the Headers tab and set the Content-Type to application/json.
5. Open the Body tab and select raw and set the type as JSON from the dropdown.
6. Enter the username and password as the payload: {"username":"<username>","password":"<password>"}
7. Click SEND.
8. If the authentication is successful, the response is 200 OK.
9. Click the Cookies tab.
10. Your authentication cookie has the name va. Use its value in subsequent API requests.
    1. By default, Postman stores the cookie and uses it in subsequent requests. You can see it in the request Headers tab as a Cookie.