Introduction

Overview

The Eagle Eye Video API is a comprehensive RESTful API for recording, indexing and storing camera video. The Eagle Eye Video API handles all the heavy lifting of interfacing with the cameras, recording video, securely transmitting video to the cloud, storing video and making video available for use for your applications. All of the Eagle Eye Security Camera VMS user interfaces (web, iOS, Android) have been built using this API

We provide language bindings in cURL. You can view code examples on the right-hand side window and you can switch the programming language of the examples with the tabs in the top right (when available)

Getting Started

The Eagle Eye Video API allows you to securely record, manage and play video back from any camera, any place, any time. A robust annotation interface and smart bandwidth management allows you to turn terabytes of raw video into searchable, useful data

Since the API is based on REST principles, it’s very easy to write and test applications. You can use your browser to access URLs and you can use many different HTTP clients in nearly any programming language

Requirements

• TLS 1.2 or greater

Get an API Key

Create a Developer Account

To get started with the Eagle Eye Video API you will need an API Key. This is used to identify you and your application. It also makes everything secure. To get an API Key you will need an account (so that you have some place to do some testing). You can either use your existing account or create a Developer Account. You can create an API Key in your existing account under the Account Settings

You will have to verify your email address to create your Developer Account. You will also get an email with a shortcut to create the API Key. Click on the shortcut link to create your API Key and get started writing some code

You may also want to purchase a development hardware kit from us (so you can connect some devices). These are available at a large discount for developers. You can get an Eagle Eye Bridge and even some Cameras from us for development and testing. Just email us for more information and pricing

The API Key should be located in the header under the 'Authorization' key with a colon appended to it

Please see the section on Single Sign On for alternatives to password authentication

Visual Steps

Content Features

Fully control the information flow:

Content

Press F8 to enable / disable Hover Modals
(onclick behavior will remain)

To close the Modal definition:

• Click outside of the Modal area
• Press the close (×) button
• Press Esc

Appearance

Press Alt + C to change the Modal color
(the color will not be changed now)

Press F9 to enable / disable an additional feature

HTTP Response Codes

Overview

We use the established HTTP status codes. This is the general description for all the codes we return. Each API call defines any additional meaning intended with the return codes it uses.

Authentication

Overview

Gaining access to the Eagle Eye API is a two-stage process. Clients first present their credentials and Realm to obtain a single-use Authentication Token. This single use token is valid for a predefined duration or until it has been used. Once the Authentication Token is obtained the Client must utilize it in an Authorize service call to obtain a session ID (via the 'auth_key' cookie) that provides access to resources. This two-phase approach allows Clients to authenticate and operate in multiple domains. The first step is done using Authenticate. The second step is done using Authorize. Note that the Authenticate call must be done over a HTTPS connection

In addition to the Simple Authentication described above, a more secure Authentication method known as Two-Factor Authentication (TFA) may be used. TFA is a method of confirming the user’s identity by utilizing a combination of two different components. The first component is a user’s password and the second is a one-time TFA code delivered to the user via another communication channel - email or a text message sent to the user’s mobile phone

Whether Simple or Two-Factor Authentication is used for a particular user’s login is determined by this user’s settings in the system. Note, however, that an Account Superuser may enforce all users in a particular Account to use TFA

If TFA is enforced, the Authorize call will expect the TFA code to be passed in addition to the token obtained from the Authenticate call

There are several methods to use the 'auth_key' cookie (obtained from the Authorize call) to authenticate subsequent API calls:

• The first is to simply pass the 'auth_key' cookie with all API requests
• The second is to take the value of the 'auth_key' cookie and pass it in the request as the 'A' parameter
  (The 'A=[AUTH_KEY]' parameter can be used with any method (GET, PUT, POST, DELETE))

The order of precedence for session ID retrieval is as follows:

1. 'A' parameter in the query string of any method (GET, PUT, POST, DELETE)
2. 'A' parameter in the POST data
3. 'A' parameter in the request body (e.g. PUT)
4. 'auth_key' cookie

Note: HTTP response status codes are listed throughout the document in order of precedence with the request successfully completed codes at the very end - meaning amongst the negative result codes the last one listed is the one that will be returned if none of the preceding codes’ conditions are met

1. Authenticate

Login is a two-step process when using Simple Authentication and a three-step process using TFA

Simple Authentication

1. Authenticate with username and password
2. Authorize with the token returned by Authenticate

Two-Factor Authentication

1. Authenticate
2. Instruct the system to send the TFA code
3. Authorize with the token received from 1. and the TFA code received from 2.

Request

curl -X POST https://login.eagleeyenetworks.com/g/aaa/authenticate -d '{"username": "[USERNAME]", "password": "[PASSWORD]"}' -H "content-type: application/json" -H "Authentication: [API_KEY]"

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/authenticate

Json Response (Simple Authentication)

{
    "token": "MiDUwMQqwP1JsfKqbqT1DQ8hJFHEOZfROEUtBvnuqv0ICxvcOybkS1n9/awjrJ9YKijb60GqdUDPP8TW4o8Ei8iI8OXC/dj74KC2cLMxJ2vs/hmYPfbW8OpCwf0k683a2LfIbjcC3Uy/SmDpOsxVdPMTXQEGJHXD3ItmAvoQ5MOoRKfHBNOu7OJBWQjPUjeP0fkHSrx8JgAHSqT5SwRM0mLysFmiFHF0h7/5Apt81dDhZwLBDwwSrl+kTqgn+wnw6rJ432liESdK+yp3Qefk1wAtytoTJkkBE2srqsHJdW4ryVYKk9SKA62Cz7pO3VUaD8Yxx9Ff2Os9ez6TdfBmqg=="
}

Json Response (Two-Factor Authentication)

{
    "token": "MiDUwMQqwP1JsfKqbqT1DQ8hJFHEOZfROEUtBvnuqv0ICxvcOybkS1n9/awjrJ9YKijb60GqdUDPP8TW4o8Ei8iI8OXC/dj74KC2cLMxJ2vs/hmYPfbW8OpCwf0k683a2LfIbjcC3Uy/SmDpOsxVdPMTXQEGJHXD3ItmAvoQ5MOoRKfHBNOu7OJBWQjPUjeP0fkHSrx8JgAHSqT5SwRM0mLysFmiFHF0h7/5Apt81dDhZwLBDwwSrl+kTqgn+wnw6rJ432liESdK+yp3Qefk1wAtytoTJkkBE2srqsHJdW4ryVYKk9SKA62Cz7pO3VUaD8Yxx9Ff2Os9ez6TdfBmqg==",
    "two_factor_authentication_code": {
        "sms": "*** *** 779",
        "email": "***********@gmail.com"
    }
}

HTTP Response (Json Attributes)

NOTE 1:

Token expiration:

• 30 seconds for Simple Authentication
• 15 minutes for TFA

NOTE 2:

For TFA, the system uses the parameter 'sms_phone' from the User Model
If SMS-based authentication is to be used, that parameter must be specified at the user’s creation time (See Create User)
If user’s parameter 'sms_phone' has not been set, the value of the 'sms' key will be 'No sms phone found'

NOTE 3:

The TFA-related user’s data (i.e. SMS phone or email), once set at the time of user’s account creation, can only be modified by that user alone. Any such modification will also be TFA authenticated. Account superuser cannot change this data for security reasons

HTTP Status Codes

*Code 412 is also returned if TFA is used and the user’s account has been locked due to more than 3 failed attempts to authorize with a TFA code

2. Send TFA Code (only if using TFA)

This step is only to be executed when TFA is used for the user log in (i.e. if the Authenticate call returned 'two_factor_authentication_code' key in response). Otherwise proceed to Step 3: Authorize

Request (Two-Factor Authentication)

curl -D - -X POST https://login.eagleeyenetworks.com/g/aaa/two_factor_authenticate -d '{"token": "[TOKEN]", "two_factor_authentication_type": "[TFA_TYPE]"}' -H "content-type: application/json" -H "Authentication: [API_KEY]"

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/two_factor_authenticate

HTTP Response

This API call does not return data in response

NOTE 1:

TFA code expiration is 15 minutes

Response Status Codes

3. Authorize

Authorize is the final step of the login process performed by utilizing the token from Authenticate and (if TFA is enabled) the TFA code delivered to the user by SMS or email. A successful Authorize call returns an authorized user object and sets the 'auth_key' cookie. For all subsequent API calls either the cookie can be set or the value of it can be sent as the 'A' parameter. When TFA is used, this call will also set the 'tfa_key' cookie (See Authorized devices for more details)

API calls can initially be done against 'https://login.eagleeyenetworks.com' (The host url), but after the authorization response is returned, API calls should then use the branded subdomain. At this stage the branded host url will become 'https://[active_brand_subdomain].eagleeyenetworks.com', where the 'active_brand_subdomain' field is returned in the authorization response

Following the authorization in the example on the right, the host url should be changed to: 'https://c001.eagleyenetworks.com'

Each account will consistently have the same branded subdomain and as such will not change throughout the life of the session. Caching the subdomain is safe as long as the client software validates against the 'active_brand_subdomain' after authorization. Using the branded subdomain is important for speed and robustness

Request (Simple Authentication)

curl -D - -X POST https://login.eagleeyenetworks.com/g/aaa/authorize -d '{"token": "[TOKEN]"}' -H "content-type: application/json" -H "Authentication: [API_KEY]"

Request (Two-Factor Authentication)

curl -D - -X POST https://login.eagleeyenetworks.com/g/aaa/authorize -d '{"token": "[TOKEN]", "two_factor_authentication_code": "[TFA_CODE]"}' -H "content-type: application/json" -H "Authentication: [API_KEY]"

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/authorize

NOTE 1:

More than 3 failed attempts to Authorize with TFA code will lock the user’s account. It then can only be unlocked by Eagle Eye’s technical support staff When the user’s account has been locked the user is notified of this fact by email

Json Response

{
    "id": "ca0e1cf2",
    "user_id": "ca0e1cf2",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@nodomain.com",
    "owner_account_id": "00004206",
    "active_account_id": "00004206",
    "uid": "",
    "is_superuser": 0,
    "is_account_superuser": 1,
    "is_staff": 0,
    "is_active": 1,
    "is_pending": 0,
    "is_master": 1,
    "is_user_admin": 1,
    "is_layout_admin": 1,
    "is_edit_map": 0,
    "is_live_video": 1,
    "is_export_video": 1,
    "is_recorded_video": 1,
    "is_view_preview_video": 1,
    "is_edit_admin_users": 1,
    "is_edit_all_users": 1,
    "is_edit_users": 1,
    "is_edit_account": 1,
    "is_device_admin": 1,
    "is_edit_cameras": 1,
    "is_edit_camera_on_off": 1,
    "is_edit_camera_less_billing": 1,
    "is_edit_ptz_stations": 1,
    "is_edit_all_and_add": 1,
    "is_edit_motion_areas": 1,
    "is_edit_sharing": 1,
    "is_ptz_live": 1,
    "is_mobile_branded": 0,
    "is_view_contract": 1,
    "is_view_audit_trail": 1,
    "is_two_factor_authentication_enabled": 0,
    "user_authenticated_clients": null,
    "account_utc_offset": -25200,
    "account_work_days": "1111100",
    "account_work_hours": [
        "0900",
        "1700"
    ],
    "language": "en-us",
    "inactive_session_timeout": 15,
    "street": [
        "address line 1",
        "address line 2"
    ],
    "city": "New York",
    "state": "Alaska",
    "country": "US",
    "postal_code": "9980-999",
    "phone": "111111111",
    "mobile_phone": "000000000",
    "utc_offset": -25200,
    "timezone": "US/Pacific",
    "last_login": "20181006173752.672",
    "alternate_email": "alternate.email@nodomain.com",
    "sms_phone": "222111222",
    "json": "{\"een\":{\"notify_levels\":[], \"permissions\":{}}}",
    "camera_access": [
        [
            "1005f2ed",
            "r"
        ],
        [
            "100bd708",
            "r"
        ],
        [...]
    ],
    "layouts": [
        "217f0fd4-450f-11e4-a983-ca8312ea370c"
    ],
    "is_notify_enable": 1,
    "notify_period": [
        "0-0000-2359",
        "1-0000-2359",
        "2-0000-2359",
        "3-0000-2359",
        "4-0000-2359",
        "5-0000-2359",
        "6-0000-2359"
    ],
    "notify_rule": [
        "one-email-0"
    ],
    "is_branded": 1,
    "active_brand_subdomain": "c001",
    "account_map_lines": null,
    "access_period": [
        "0-0000-2359",
        "1-0000-2359",
        "2-0000-2359",
        "3-0000-2359",
        "4-0000-2359",
        "5-0000-2359",
        "6-0000-2359"
    ],
    "user_log_level": 0,
    "saved_filters": [],
    "temp_account_access": [],
    "is_terms_noncompliant": 1,
    "is_system_notifications_disabled": 0
}

HTTP Response (Json Attributes)

When successful, this API call returns Json data structure following the User Model with the additional 'user_id' field, which is present during Authorize and is identical to 'id'

HTTP Status Codes

When using Simple Authentication

When using TFA

Forced vs. Optional TFA

Depending whether the account to which the user belongs enforces TFA or not, the user may be able to select Simple Authentication for their future Logins rather than TFA

In order to find out whether the account enforces TFA examine the 'is_two_factor_authentication_forced' flag in the account record returned by the Get Account API Call. This flag can be set or cleared by the account superuser with the Update Account API call

If the account TFA flag is set as follows 'is_two_factor_authentication_forced=0', the user is allowed switch to Simple Authentication. That is achieved by clearing 'is_two_factor_authentication_enabled=1' flag in the user record. This action can only be done by the user themselves (not by an account superuser)

Update of any TFA-related field in the user record is performed through a dedicated TFA update endpoint: '/g/aaa/two_factor_authenticate/update'

TFA Update

Data present in the user record that affects the TFA is security-sensitive and therefore may only be altered using a dedicated endpoint, whose operation is itself TFA protected. This data includes three fields in the user model:

TFA Update is a two-step process:

1. Request Update

This step initiates the TFA data update process

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/two_factor_authenticate/update

HTTP Response

This API call returns no data

2. Verify update request with TFA

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/two_factor_authenticate/verify

HTTP Response

This API call returns no data

Authorized Devices

In order to make the log-in process as convenient as possible for the user, the system will allow Simple Authentication on devices previously used by that user for a successful TFA-based log in

Upon a successful TFA-based log in, the Authorize API call sets a cookie 'tfa_key' in the browser. Subsequent execution of the Authenticate API Call with the correct username and password will initiate the Simple Authentication process, which can be differentiated from TFA by absence of the 'two_factor_authentication_code' field in the response of Authenticate. In this scenario the Send TFA Code API call can be skipped and the Authorize API call can be executed directly as via the non-TFA-enabled login

NOTE 1:

The same 'tfa_key' value may be applied for multiple users, who have successfully authorized in the past from the particular device

NOTE 2:

The list of authorized devices for any user is stored in the field 'user_authenticated_clients' in the user record (See User Model)

AAA

Overview

This service enables the creation of new Independent Accounts and provides the means to recover them. If you are creating Sub-Accounts tied to your current Account refer to the Account section

Create Account

Create a new account and the superuser for the account. As a part of the creation process, the service sends a confirmation email containing a link (with Account ID and activation token), which the user must click to activate the account (cannot be used until it is activated)

Request

curl -X POST https://login.eagleeyenetworks.com/g/aaa/create_account -d "email=[EMAIL]" -d "password=[PASSWORD]" -H "Authentication: [API_KEY]" -v

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/create_account

HTTP Status Codes

Validate Account

Verify the email address supplied when the account is created. When successful, the account is set to active and a user session is created. User will not be required to login again

Request

curl -X POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/validate_account -d "id=[ID]" -d "token=[TOKEN]" -H "Authentication: [API_KEY]"

For information on active_brand_subdomain click here.

HTTP Request

POST https://login.eagleeyenetworks.com/g/aaa/validate_account

Json Response

{
    "user_id": "ca103fea"
}

HTTP Response (Json Attributes)

HTTP Status Codes

1. Forgot Password

Password recovery is a multi-step process:

1. Forgot Password requests a reset email to be sent to the email address of a registered user
2. Check Password Reset Token verifies whether the reset token is valid (This step is optional but is provided to allow for a friendlier user experience)
3. Reset Password allows the user to change the password (This step directly verifies whether the supplied token is a valid reset token). The result is that a user session is created for the user

Request

curl -X POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/forgot_password -d "email=[EMAIL]" -H "Authentication: [API_KEY]" -v

For information on active_brand_subdomain click here.

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/forgot_password

HTTP Status Codes

2. Check Password Reset Token

This is step two of the password recover/reset process. It verifies that the supplied token is a valid reset token

Request

curl -X POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/check_pw_reset_token -d "token=[TOKEN]" -H "Authentication: [API_KEY]" -v

For information on active_brand_subdomain click here.

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/check_pw_reset_token

HTTP Status Codes

3. Reset Password

This is step three of the password recover/reset process. It both verifies that the supplied token is a valid reset token and then, if valid resets the password associated with the token to the newly supplied password. Upon completion, a user login session is created

Request

curl -X POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/reset_password -d "password=[PASSWORD]" -d "token=[TOKEN]" -H "Authentication: [API_KEY]"

For information on active_brand_subdomain click here.

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/reset_password

Json Response

{
    "user_id": "ca0e1cf2"
}

HTTP Response (Json Attributes)

HTTP Status Codes

Validation of the new password against Account’s password rules

Response Json object with failed requirements for the new password:

{
    "status_code": 400,
    "message": "New password does not meet all of the requirements.",
    "data": {
        "failed_requirements": {
            "same_password": {
              "description": "New password cannot be the same as the old one."
            },
            "length": {
                "description": "Password length must be between 12 and 126 characters long.",
                "required_value": {
                    "minimum_length": 12,
                    "maximum_length": 126
                }
            },
            "reuse": {
                "description": "Previous passwords cannot be reused."
            },
            "required_special_char": {
                "description": "New password needs to contain at least one symbol."
            },
            "required_numeric_char": {
                "description": "New password needs to contain at least one number."
            },
            "exclude_username": {
                "description": "New password should not contain the username."
            },
        }
    },
    "reason": "InvalidPassword"
}

If a new password fails against some of the Account’s password requirements, HTTP response with status code 400 and JSON object will be returned.

Most password management settings require feature flag, if you want to enable it ask support.

More details on Password management rules can be found here.

Resend Registration Email

For users who have registered for an account, but never confirmed the registration. This will allow the registration confirmation email to be re-sent

Request

curl -X POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/resend_registration_email -d "email=[EMAIL]" -H "Authentication: [API_KEY]" -v

For information on active_brand_subdomain click here.

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/resend_registration_email

HTTP Status Codes

Resend User Verification Email

For users who have had a user account created, but never confirmed their user account. This will allow the user confirmation email to be re-sent

Request

curl -X POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/resend_user_verification_email -d "email=[EMAIL]" -H "Authentication: [API_KEY]" -v

For information on active_brand_subdomain click here.

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/resend_user_verification_email

HTTP Status Codes

Change Password

This allows a user to change their password directly while authenticated and also allows super users to change the password of the users they manage:

• While changing the own password, the current password needs to be provided as well (User ID should be omitted)
• While changing the password of one of the managed users only the new password is required (aside from the managed user’s ID)

Request

curl -X POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/change_password -d "password=[PASSWORD]" -d "current_password=[CURRENT_PASSWORD]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]"

For information on active_brand_subdomain click here.

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/change_password

Json Response

{
    "id": "ca02c000"
}

HTTP Response (Json Attributes)

HTTP Status Codes

Switch Account

Allows a user to ‘log in’ to another account which the they have access to (see Get List of Accounts). Most commonly this would be needed for a master account user accessing their sub-accounts. Only applicable to accounts from the Account model

Request

curl -X POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/switch_account -d "account_id=[ID]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -v

For information on active_brand_subdomain click here.

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/switch_account

HTTP Status Codes

Single Sign On

SSO allows a reseller to maintain account management and act as an identity provider to have their system proxy the authorization requests to Eagle Eye Network servers after users have logged into the identity providers system. This is done through the standard SAML V2.0 (Security Assertion Markup Language)

Authenticate request

Request authentication from an Identity Provider Service. (Service provider initiated SSO)

HTTP Request

GET https://<branded_sub_domain>.eagleeyenetworks.com/g/aaa/sso/SAML2/SSO

After the successful creation of SAML AuthnRequest, redirection to the Identity Provider is going to be made.
If a user is authenticated in the Identity Provider Service, redirection to the Service Provider ACS (Assertion Consumer Service) is going to be made.

ACS (Assertion Consumer Service)

Decoded SAML response example

<saml2p:Response 
    Destination="https://branded_subsomain.eagleeyenetworks.com/g/aaa/sso/SAML2/Authenticate" 
    ID="id8972425978818166328589959" 
    IssueInstant="2019-11-05T16:53:17.411Z" 
    Version="2.0" 
    xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
    ...
    <saml2:Assertion 
        ID="id89724259788888402047455941" 
        IssueInstant="2019-11-05T16:53:17.411Z" 
        Version="2.0" 
        xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" 
        xmlns:xs="http://www.w3.org/2001/XMLSchema">
        <saml2:Issuer 
            Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity" 
            xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">exk1huy3reR4Fs9gL357
        </saml2:Issuer>
        <ds:Signature 
            xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo>
                <ds:CanonicalizationMethod 
                    Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                <ds:SignatureMethod 
                    Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                <ds:Reference 
                    URI="#id89724259788888402047455941">
                    <ds:Transforms>...<ds:DigestMethod 
                        Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                    <ds:DigestValue>...</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>...</ds:SignatureValue>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>...</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
        <saml2:Subject 
            xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml2:NameID 
                Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">orion@belt.com
            </saml2:NameID>
            <saml2:SubjectConfirmation 
                Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData 
                    NotOnOrAfter="2019-11-05T16:58:17.411Z" 
                    Recipient="https://branded_subsomain.eagleeyenetworks.com/g/aaa/sso/SAML2/Authenticate"/>
            </saml2:SubjectConfirmation>
        </saml2:Subject>
        <saml2:Conditions 
            NotBefore="2019-11-05T16:48:17.411Z" 
            NotOnOrAfter="2019-11-05T16:58:17.411Z" 
            xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
        </saml2:Conditions>
        <saml2:AuthnStatement 
            AuthnInstant="2019-11-05T16:53:17.411Z" 
            SessionIndex="id1572972797411.929762837" 
            xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml2:AuthnContext>
                <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:X509</saml2:AuthnContextClassRef>
            </saml2:AuthnContext>
        </saml2:AuthnStatement>
        <saml2:AttributeStatement 
            xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml2:Attribute 
                Name="firstName" 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
                <saml2:AttributeValue 
                    xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:type="xs:string">Orion
                </saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute 
                Name="lastName" 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
                <saml2:AttributeValue 
                    xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:type="xs:string">Belt
                </saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute 
                Name="access" 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
                <saml2:AttributeValue 
                    xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                </saml2:AttributeValue>
            </saml2:Attribute>
        </saml2:AttributeStatement>
    </saml2:Assertion>
</saml2p:Response>

(Identity provider initiated SSO)

HTTP Request

POST https://<branded_sub_domain>.eagleeyenetworks.com/g/aaa/sso/SAML2/Authenticate

Suported SAML elements

• NameID: The element which holds user email.
  
• Issuer: Identity Provider identifier to match SAML response with an appropriate account.
  
• Conditions: Additional conditions on the use of the assertion can be provided inside this element. Currently supported: NotBefore and NotOnOrAfter.

Attribute Statement

Single Log Out

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/sso/SAML2/LogOut

This is done through the standard SAML2 (Security Assertion Markup Language) and as such the identity provider will setup their account with a brand_saml_publickey_ret and brand_saml_namedid_path

• The brand_saml_publickey_cert is a x509 certificate that contains a public key with which Eagle Eye Networks can validate that an SSO message is valid and verify that it has not been altered. The format of this certificate is PEM (ascii encoded base 64 surrounded by lines containing ‘—–BEGIN CERTIFICATE——‘ and '——END CERTIFICATE——’

• The brand_saml_namedid_path is the xml xpath to the node that contains the email address of the user being logged in

Once the identity provider’s account has been registered for SSO, then the identity provider can validate their users and then make a single sign on request with the users email address and the return link This 64 bit encrypted message will be extracted from the header to be decoded and verified using the saml public key Then using the saml named ID path, the user’s email will be extracted and an 'auth_key' will be provided for that user

Request

curl -X POST https://login.eagleeyenetworks.com/g/sso -H "Authentication: [API_KEY]"

HTTP Request

POST https://login.eagleeyenetworks.com/g/sso

Check Authentication is valid

This call allows you to check if the current authentication is still valid. This is helpful to use before making subsequent calls using existing authentication.

Request

curl -X GET https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/isauth -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -v

For information on active_brand_subdomain click here.

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/isauth

HTTP Status Codes

Logout

Log out user and invalidate HTTP session cookie

Request

curl -X POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/logout -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -v

For information on active_brand_subdomain click here.

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/aaa/logout

HTTP Status Codes

Account

Overview

The Account service allows managing Accounts by superusers and account superusers

Account Model

Account Model

{
    "is_master_video_disabled_allowed": 1,
    "is_inactive": 0,
    "is_suspended": 0,
    "brand_name": null,
    "alert_mode": [
        "default",
        "Weekend"
    ],
    "is_master_video_disabled": 0,
    "contact_state": null,
    "first_responders": [
        [
            "mark@responders.com",
            "Mark",
            "O'Malley",
            "Responders",
            "Fake Account"
        ],
        [
            "jeff@noaccount.com",
            "Jeff",
            "O'Unverified",
            "Unverified Organization",
            "No Account"
        ],
        [...]
    ],
    "responder_cameras": [
      "12345678",
      "1010fake"
    ],
    "contact_first_name": "Willem",
    "is_disable_all_settings": 0,
    "timezone": "US/Pacific",
    "id": "11111111",
    "contact_country": "US",
    "is_system_notifications_disabled": 0,
    "camera_shares": [
        [
            "12345678",
            "joe@em.com,His account",
            "joe2@dd.com,That account"
        ],
        [...]
    ],
    "camera_share_perms": {
        "12345678": {
            "joe@em.com,His account": [
                "edit_motion_areas",
                "ptz_live",
                "edit_ptz_stations"
            ],
            "joe2@dd.com,That account": [
                "ptz_live"
            ]
        },
        "<camera_id>": {...}
    },
    "owner_account_id": "1010101b",
    "product_edition": null,
    "cc_info": [
        {
            "city": "",
            "name": "",
            "default": "",
            "street1": "",
            "street2": "",
            "number": "",
            "state": "",
            "tag": "",
            "postal_code": "",
            "expire": "",
            "country": "US",
            "type": ""
        }
    ],
    "brand_saml_publickey_cert": null,
    "brand_support_email": null,
    "is_billing_disabled": 0,
    "is_advanced_disabled": 0,
    "inactive_session_timeout": 720,
    "brand_logo_large": null,
    "brand_corp_url": null,
    "responder_active": true,
    "contact_street": [],
    "is_system_notification_images_enabled": 1,
    "is_custom_brand_allowed": 0,
    "is_rtsp_cameras_enabled": 0,
    "brand_saml_nameid_path": null,
    "is_contract_recording": 0,
    "utc_offset": -28800,
    "session_duration": 480,
    "is_custom_brand": 0,
    "contact_postal_code": null,
    "brand_logo_small": null,
    "is_active": 1,
    "work_days": "1111111",
    "is_add_delete_disabled": 0,
    "is_master": 0,
    "contact_email": "support@eagleeyenetworks.com",
    "brand_support_phone": null,
    "map_lines": null,
    "contact_mobile_phone": null,
    "work_hours": [
        "0800",
        "1730"
    ],
    "login_attempt_limit": null,
    "default_cluster": "c000",
    "customer_id": "1234",
    "name": "Account Name",
    "contact_city": null,
    "default_camera_passwords": "pwordpword",
    "contact_phone": null,
    "access_restriction": [
        "enable_mobile"
    ],
    "active_alert_mode": "default",
    "allowable_ip_address_range": [],
    "contact_last_name": "Dafoe",
    "contact_utc_offset": null,
    "camera_quantity": null,
    "brand_subdomain": "c000",
    "password_management_rules": {
        "allowed_minimum_length": 10,
        "allowed_maximum_length": 64,
        "days_to_expire": 0,
        "exclude_username": 0,
        "minimum_length": 10,
        "maximum_length": 126,
        "required_numeric_char": 0,
        "required_special_char": 0,
        "reuse_number_limit": 0,
        "reuse_time_limit": 0
    }
}

Account (Attributes)

Account - camera_share_perms - <camera_id>

Account - camera_share_perms - <camera_id> - <share_recipients>

Account - password_management_rules

Parameters of password_management_rules object. On password change by default users are disallow to set previous password.

Length requirements

Character requirements

Reuse requirements

Other requirements

Account - idp_settings

Account’s IdP (Identity Provider) settings.

Notes on IdP settings in the context of the accounts hierarchy
There are three possible mutually exclusive modes of IdP configuration:

1. SSO is disabled for all accounts (master and its subs)
   The standard login page is going to be loaded if an unauthenticated user requests EEN site.

2. SSO enabled on the master account
   All of the accounts (master and its subs) use the master account’s IdP settings to SSO.

3. SSO allowed for the sub-accounts
   Sub-accounts can have an individual set of settings for IdP to SSO. SSO to master account is disabled.

SSO Modes expressed with a master account idp_settings values

Get Account

Returns an Account object by ID

Request

curl -X GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account -d "id=[ACCOUNT_ID]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -G

For information on active_brand_subdomain click here.

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account

HTTP Status Codes

Create Account

Create a new Account

Request

curl -X PUT https://[active_brand_subdomain].eagleeyenetworks.com/g/account -d '{"name": "[NAME]", "contact_first_name": "[CONTACT_FIRST_NAME]", "contact_last_name": "[CONTACT_LAST_NAME]", "contact_email": "[CONTACT_EMAIL]"}' -H "content-type: application/json" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]"

For information on active_brand_subdomain click here.

HTTP Request

PUT https://[active_brand_subdomain].eagleeyenetworks.com/g/account

Json Response

{
    "id": "1234abcd"
}

HTTP Response (Json Attributes)

HTTP Status Codes

Update Account

Update Account information

Request

curl -X POST https://[active_brand_subdomain].eagleeyenetworks.com/g/account -d '{"id": "[ACCOUNT_ID]", "contact_first_name": "[CONTACT_FIRST_NAME]"}' -H "content-type: application/json" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]"

For information on active_brand_subdomain click here.

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/account

Json Response

{
    "id": "1234abcd"
}

HTTP Response (Json Attributes)

HTTP Status Codes

Delete Account

Delete an Account

Request

curl -X DELETE https://[active_brand_subdomain].eagleeyenetworks.com/g/account -d "id=[ACCOUNT_ID]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -G

For information on active_brand_subdomain click here.

HTTP Request

DELETE https://[active_brand_subdomain].eagleeyenetworks.com/g/account

HTTP Status Codes

Get List of Accounts

Returns an array of arrays with each sub-array representing an Account available to the user

Request

curl -X GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/list -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -G

For information on active_brand_subdomain click here.

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/list

Json Response

[
    [
        "00004206",
        "Greater God",
        0,
        0,
        1,
        0,
        0,
        1,
        null,
        0,
        0,
        0,
        0,
        0,
        0,
        "20180228234555.722",
        0,
        "Greater ID",
        0,
        {"is_sso_enabled":0, "timezone":"US/Central", "feature_flags":[]},
        "A@GFIMLNQSUTYZcedgfhmqpsutvz"
    ],
    [...],
    [...],
    [...]
]

HTTP Response (Array Attributes)

Account - json

Account - json

HTTP Status Codes

Account Statistics

This service allows to retrieve Statistics about a specific Account or all Sub-Accounts (for a Master Account)

Obtains the total amount of:

• Sub-Accounts
• Users
• Bridges
• Cameras
• Online Users
• Online Cameras

Each statistics request extends the /g/account endpoint in the following way /g/account/statistics/<type_of_statistic>

Total Number of Sub-Accounts

Used to get the number of all sub-accounts for the specific account

Request

curl -X GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/sub_accounts -d "account_id=[ACCOUNT_ID]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -G

For information on active_brand_subdomain click here.

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/sub_accounts

Json Response

{
    "account_total": 6
}

HTTP Response (Json Attributes)

HTTP Status Codes

Total Number of Users

Used to get the number of all users for the specific account

Request

curl -X GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/users -d "account_id=[ACCOUNT_ID]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -G

For information on active_brand_subdomain click here.

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/users

Json Response

{
    "user_total": 26
}

HTTP Response (Json Attributes)

HTTP Status Codes

Total Number of Bridges

Used to get the number of all bridges for the specific account

Request

curl -X GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/bridges -d "account_id=[ACCOUNT_ID]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -G

For information on active_brand_subdomain click here.

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/bridges

Json Response

{
    "bridge_total": 1
}

Total Number of Cameras

Used to get the number of all cameras for the specific account

Request

curl -X GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/cameras -d "account_id=[ACCOUNT_ID]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -G

For information on active_brand_subdomain click here.

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/cameras

Json Response

{
    "camera_total": 8
}

HTTP Response (Json Attributes)

HTTP Status Codes

HTTP Response (Json Attributes)

HTTP Status Codes

Total Number of Online Users

Used to get the number of all online users for the specific account

Request

curl -X GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/online_users -d "account_id=[ACCOUNT_ID]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -G

For information on active_brand_subdomain click here.

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/online_users

Json Response

{
    "online_user_total": 6
}

HTTP Response (Json Attributes)

HTTP Status Codes

Total Number of Online Cameras

Used to get the number of all online cameras for the specific account

Request

curl -X GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/online_cameras -d "account_id=[ACCOUNT_ID]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -G

For information on active_brand_subdomain click here.

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/account/statistics/online_cameras

Json Response

{
    "camera_online_total": 5
}

HTTP Response (Json Attributes)

HTTP Status Codes

User

Overview

The User service allows managing Users to a degree outlined by the permission level

User Model

User Model

{
    "id": "ca0e1cf2",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@nodomain.com",
    "owner_account_id": "00004206",
    "active_account_id": "00004206",
    "uid": "",
    "is_superuser": 0,
    "is_account_superuser": 1,
    "is_staff": 0,
    "is_active": 1,
    "is_pending": 0,
    "is_master": 1,
    "user_pin": 342141,
    "is_user_admin": 1,
    "is_layout_admin": 1,
    "is_user_create_layout": 1,
    "is_edit_map": 1,
    "is_live_video": 1,
    "is_export_video": 1,
    "is_recorded_video": 1,
    "is_view_preview_video": 1,
    "is_edit_admin_users": 1,
    "is_edit_all_users": 1,
    "is_edit_users": 1,
    "is_edit_account": 1,
    "is_device_admin": 1,
    "is_edit_cameras": 1,
    "is_edit_camera_on_off": 1,
    "is_edit_camera_less_billing": 1,
    "is_edit_ptz_stations": 1,
    "is_edit_all_and_add": 1,
    "is_edit_motion_areas": 1,
    "is_edit_sharing": 1,
    "is_ptz_live": 1,
    "is_mobile_branded": 0,
    "is_view_contract": 1,
    "is_view_audit_trail": 1,
    "is_two_factor_authentication_enabled": 0,
    "user_authenticated_clients": null,
    "account_utc_offset": -25200,
    "account_work_days": "1111100",
    "account_work_hours": [
        "0900",
        "1700"
    ],
    "language": "en-us",
    "inactive_session_timeout": 15,
    "street": [
        "address line 1",
        "address line 2"
    ],
    "city": "New York",
    "state": "Alaska",
    "country": "US",
    "postal_code": "9980-999",
    "phone": "111111111",
    "mobile_phone": "000000000",
    "utc_offset": -25200,
    "timezone": "US/Pacific",
    "last_login": "20181006173752.672",
    "alternate_email": "alternate.email@nodomain.com",
    "sms_phone": "222111222",
    "json": "{\"een\":{\"notify_levels\":[], \"permissions\":{}}}",
    "camera_access": [
        [
            "1005f2ed",
            "r"
        ],
        [
            "100bd708",
            "r"
        ],
        [...]
    ],
    "layouts": [
        "217f0fd4-450f-11e4-a983-ca8312ea370c"
    ],
    "is_notify_enable": 1,
    "notify_period": [
        "0-0000-2359",
        "1-0000-2359",
        "2-0000-2359",
        "3-0000-2359",
        "4-0000-2359",
        "5-0000-2359",
        "6-0000-2359"
    ],
    "notify_rule": [
        "one-email-0"
    ],
    "is_branded": 1,
    "active_brand_subdomain": "c001",
    "account_map_lines": null,
    "access_period": [
        "0-0000-2359",
        "1-0000-2359",
        "2-0000-2359",
        "3-0000-2359",
        "4-0000-2359",
        "5-0000-2359",
        "6-0000-2359"
    ],
    "user_log_level": 0,
    "saved_filters": [],
    "temp_account_access": [],
    "is_terms_noncompliant": 1,
    "is_system_notifications_disabled": 0
}

User (Attributes)

User - json

User - json - een

Permissions

User Types

• Superuser (INTERNAL USE ONLY)
• Staff (INTERNAL USE ONLY)
• Account Superuser
• Regular User

Account superuser

The account superuser has a full set of permissions. This user can manage all users in their account and sub-account

Regular user

After being created the regular user has several default permissions : 'is_live_video', 'is_recorded_video', 'is_export_video'

List of Permissions

User Permission Matrix

The table below shows which user management actions a user can execute depending on the account they belong to and which permission flags they have enabled

TFA Enforcing

The following entities can edit the Two-Factor Authentication settings for an account:

• The Superuser is able to force TFA for:
  • Any Sub-Account from within the Master Account
  • The Sub-Account they have currently switched into
• The Account Superuser is able to force TFA for:
  • The Sub Account in which they have been granted administrator permissions

Get User

Returns a User object by ID

Request

curl -X GET https://[active_brand_subdomain].eagleeyenetworks.com/g/user -d "id=[USER_ID]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -G

For information on active_brand_subdomain click here.

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/user

HTTP Status Codes

Create User

Create a new User. After being created the user is in the pending state ('is_pending=1', 'is_active=0'). The user creation email will be sent to the email address passed in the request. Then the user will be able to enter a password (In this step they may need to accept Terms of Service). After this operation the user will be active ('is_pending=0', 'is_active=1')

Request

curl -X PUT https://[active_brand_subdomain].eagleeyenetworks.com/g/user -d '{"first_name": "[FIRST_NAME]", "last_name": "[LAST_NAME]", "email": "[EMAIL]"}' -H "content-type: application/json" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]"

For information on active_brand_subdomain click here.

HTTP Request

PUT https://[active_brand_subdomain].eagleeyenetworks.com/g/user

Json Response

{
    "id": "ca0ffa8c"
}

HTTP Response (Json Attributes)

HTTP Status Codes

Update User

Update User information

Request

curl -X POST https://[active_brand_subdomain].eagleeyenetworks.com/g/user -d '{"id": "[USER_ID]", "first_name": "[FIRST_NAME]"}' -H "content-type: application/json" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]"

For information on active_brand_subdomain click here.

HTTP Request

POST https://[active_brand_subdomain].eagleeyenetworks.com/g/user

Json Response

{
    "id": "ca0ffa8c"
}

HTTP Response (Json Attributes)

HTTP Status Codes

Delete User

Delete a User

Request

curl -X DELETE https://[active_brand_subdomain].eagleeyenetworks.com/g/user -d "id=[USER_ID]" -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]" -G

For information on active_brand_subdomain click here.

HTTP Request

DELETE https://[active_brand_subdomain].eagleeyenetworks.com/g/user

HTTP Status Codes

Get List of Users

Returns array of arrays with each sub-array representing a User available to the current User

Request

curl --request GET https://[active_brand_subdomain].eagleeyenetworks.com/g/user/list -H "Authentication: [API_KEY]" --cookie "auth_key=[AUTH_KEY]"

For information on active_brand_subdomain click here.

HTTP Request

GET https://[active_brand_subdomain].eagleeyenetworks.com/g/user/list

Json Response

[
    [
        "ca0555c7",
        "Katherine",
        "Xiao",
        "katherine.xiao@fakeemail.com",
        [
            "export_video",
            "recorded_video",
            "live_video",
            "device_admin",
            "layout_admin",
            "account_superuser",
            "user_admin",
            "active"
        ],
        "20180929154619.000",
        { 
            "weekly_newsletter": 0
        }
    ],
    [
        "ca00783b",
        "George",
        "Adams",
        "george.adams@fakeemail.com",
        [
            "export_video",
            "recorded_video",
            "live_video",
            "active"
        ],
        "20180716205645.000",
        { 
            "weekly_newsletter": 1
        }
    ],
    [...],
    [...],
    [...]
]