Introduction

The Eagle Eye Networks API v3 uses the OAuth2 "Authorization code" grant type to authenticate a user. This can be used to connect an Eagle Eye user with a third-party system.

The goal of this guide is to explain how to authenticate using the OAuth2 "Authorization code" grant type to get a set of tokens. These tokens can be used directly by a third-party application, and can also be used for backend-to-backend API calls between the Eagle Eye Video API Platform and a third-party system.

If you would rather skip the guide and get the access token to use in Postman or any other API client, go to My Application.

Phase 1: Granting access to a third-party app

🚧
Important
Eagle Eye users need to explicitly grant access to third-party applications. This procedure cannot be automated.

📘
Note
Only the initial authorization (Phase 1) requires human action, the machine to machine authorization (Phase 2) can be fully automated.

Before you begin

Following redirects should be enabled.
The redirect URI should be whitelisted and include a protocol (https\:// or http\://). For testing with localhost IP, it has to be, for example: <http://127.0.0.1:3333>. To whitelist a redirect URI please email [email protected].

Procedure

Make the request as HTTP POST or HTTP GET, or go to your browser of choice.
Redirect the user to auth.eagleeyenetworks.com, to the login screen with the URL shown below:

  'https://auth.eagleeyenetworks.com/oauth2/authorize?scope=vms.all&client_id={clientId}&response_type=code&redirect_uri={URI with http(s)://}' /

The {client_id} value should be the client ID, part of the Client Credentials. Always make sure that your client secret remains private.

🚧
Important
The redirect URI must exactly match the one in the example (<http://127.0.0.1:3333>). Since whitelist checking is based on string comparison, any other formats, such as <https://127.0.0.1:3333> or http://localhost:3333 or 127.0.0.1:3333/ will not work.

If the user is not yet logged in, they need to log in to Eagle Eye Networks on the following screen:

After logging in, the user is redirected to the redirect URI with an additional code parameter: <redirect_uri>?code=<code parameter>, for example: https://example.com/?code=AbCdEf.

Use this code to get the access token and refresh token.

curl -X 'POST' \
  'https://auth.eagleeyenetworks.com/oauth2/token?grant_type=authorization_code&client_id={clientId}&code={AbCdEf}&redirect_uri={URI with http(s)://}' \
  -H 'accept: application/json' \
  -d ''

For a backend application, it is more efficient to request an access token and a refresh token. This way the user does not have to sign in again. This can also be used for mobile applications that can store the refresh token in a keychain.

To request both tokens, add the Client Credentials to the authorization headers.

🚧
Important

Make sure to add the accept application/json header to the HTTP POST request.

Make sure the redirect URI parameter is the same as in the previous request, otherwise the request fails.

If a refresh token is required, make sure you perform this API call with your application server, and not in the browser. If you perform this API call in the browser, you will expose your API key and the user's refresh token.

The Authorization header uses basic authentication. Make sure to encode your \<client_id>:\<client_secret> with Base64.

Example:

curl -X 'POST' \
	'Headers HTTP POST: https://auth.eagleeyenetworks.com/oauth2/token?grant_type=authorization_code&scope=vms.all&code=AbCdEf&redirect_uri=https%3A%2F%2Fexample.com' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0' \
  -d ''


Response:
{
    "access_token": "eyJraWQiOiI2ODYxYjBjYS0wZjI2LTExZWQtODYxZC0wMjQyYWMxMjAwMDIiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjYTBmNjFhYiIsImF1ZCI6InZtcy5hcGkiLCJpc3MiOiJ2bXMuYXV0aC52MSIsInZtc19hY2NvdW50IjoiMDAwMDExMDYiLCJleHAiOjE2NjAzNjA0ODksImlhdCI6MTY2MDMxNzI4OSwianRpIjoiODJlNWMyMDQ1OTM1OTczNGYyOTU4NjlkZDhlYzIyMDMiLCJjbGllbnRfaWQiOiJCTVRPLVRFU1QiLCJ2bXNfY2x1c3RlciI6ImMwMDAifQ.JuUiozX0XMKz0kuFJTGsNFRdxOKNV4R6iRW8t6N-FpElU4sWBLhyioIot3dV2GFnHWpY5wzdFWuwVxuSvYRwhPGs6sYt4Uo0pWsrI6a9WylyavacjSmLuljdnplUzKuoB3BzohCrQGCUmiMFJ8eA4jNZnViuQ7ouKRoM4mbTSdwy_YUoNm4F7GDBiHp6TEoMFscUDlWzC-GJwVMklRGAAw_9OTTl-CGWt-CngqL1K-2Qt-3iS0WY1Jpal3-YMlJ1FVTDDuCgVIluemaH2g7ScEOM5vEnpj31H_6Gu7R9NB5CDzLaEDm2MHRJThId1-3kyhreG3Ux-WV2TAOzGbLnkg",
    "token_type": "Bearer",
    "refresh_token": "w1P0nwA7NEZmo5tEd76cco3y5bi4Js6QNgZsXnFNBDRepnJmA2F73tGJ4G_eA0WttI_8xsovsFLvd5uOUayqrNwu7PZ1SH0DAWVZ3",
    "expires_in": 43199,
    "scope": "vms.all"
}

Result: You obtained the access token and Base URL. The returned access token can be used for accessing the user data. For example, to get a camera overview or recording.

Phase 2: Machine to machine (M2M) authentication

M2M Authentication with an expiring refresh token

Once the refresh token is obtained, it can be used for logging in again. The refresh token replaces the username and password. Instead of storing username and password combinations, the database stores the refresh tokens. This way the customer's password is never stored anywhere or could be exposed.

🚧
Important
It is recommended to store the refresh token in a secure place. The refresh token should never be exposed.

📘
Notes

With the refresh token it is possible to log in without knowing the user's password. By passing along the refresh token in the query string, it is possible to obtain a new access token, which can be used for performing any API calls.

Client Credentials are passed along via HTTP basic authentication. To use basic authentication, you need to encode your \<client_id>:<secret> in Base64. See line 3 in the following example.

If the refresh token has expired, the user needs to log in again using their credentials (email and password). This can be prevented by updating the refresh token after every login.

The response also provides a new refresh token that can be used once the new access token is about to expire.

A refresh token is only generated for confidential clients. For public clients this option is not available; they need to log in again. This is done in order to ensure the data security of our partners and customers.

See the following example for logging in using the refresh token

curl --location --request POST 'https://auth.eagleeyenetworks.com/oauth2/token?grant_type=refresh_token&refresh_token=P1m_7oFP2Ful4yVGh5Z9QcQlGygiMaz0uah3QvqUbZpfufBSmpr9P6dPvlBP_1EhKS1WjyUcFGxQZrEewn62X1Og0Ww1ns3wA0ah5jJHowabYlHoYS0DAg7QUE6_mZFT' \
--header 'Accept: application/json' \
--header 'Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0' \
--data-raw ''
 
Response:
{
    "access_token": "eyJraWQiOiI2ODYxYjBjYS0wZjI2LTExZWQtODYxZC0wMjQyYWMxMjAwMDIiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjYTBmNjFhYiIsImF1ZCI6InZtcy5hcGkiLCJpc3MiOiJ2bXMuYXV0aC52MSIsInZtc19hY2NvdW50IjoiMDAwMDExMDYiLCJleHAiOjE2NjAzNjA0ODksImlhdCI6MTY2MDMxNzI4OSwianRpIjoiODJlNWMyMDQ1OTM1OTczNGYyOTU4NjlkZDhlYzIyMDMiLCJjbGllbnRfaWQiOiJCTVRPLVRFU1QiLCJ2bXNfY2x1c3RlciI6ImMwMDAifQ.JuUiozX0XMKz0kuFJTGsNFRdxOKNV4R6iRW8t6N-FpElU4sWBLhyioIot3dV2GFnHWpY5wzdFWuwVxuSvYRwhPGs6sYt4Uo0pWsrI6a9WylyavacjSmLuljdnplUzKuoB3BzohCrQGCUmiMFJ8eA4jNZnViuQ7ouKRoM4mbTSdwy_YUoNm4F7GDBiHp6TEoMFscUDlWzC-GJwVMklRGAAw_9OTTl-CGWt-CngqL1K-2Qt-3iS0WY1Jpal3-YMlJ1FVTDDuCgVIluemaH2g7ScEOM5vEnpj31H_6Gu7R9NB5CDzLaEDm2MHRJThId1-3kyhreG3Ux-WV2TAOzGbLnkg",
    "refresh_token": "Mp4k-iSQYwZ3074_e5LUJ2A01BBm5QZ6H5hE_PrGsK5edxptWsgpXQ2QxfVwrqi8MC6jhdY72y5rWA1-5znkb_QSqfF0GXLYz9m1DrUYPQ2dJRouBrK2lv5xYZerV-7D",
    "scope": "vms.all",
    "token_type": "Bearer",
    "expires_in": 86400
}

M2M authentication using non-rotating permanent refresh tokens

While we highly recommend to architect your application to accommodate refresh token rotation, Eagle Eye Networks provides an option to use a non-rotating, permanent refresh token. Unlike the standard refresh tokens that expire after 90 days, this permanent refresh token does not have an expiration date.

To enable this feature for your Client Credentials, contact [email protected], and our support team will assist you with this process.

📘
Please Note
The permanent refresh token is only applicable to refresh tokens requested by a refresh token. If the login process takes place by entering a username and password on the Eagle Eye login page, the refresh token will be different.

🚧
Important
Non-rotating refresh tokens might be deprecated in the future by the OAuth organization due to security concerns. In light of this potential change, we strongly encourage developers to implement refresh token rotation within their applications, as it aligns with best practices for maintaining a secure authentication process.

Example script for implementing OAuth

# Loggin in using OAuth follows 3 steps
# Step 1: redirect the user to auth.eagleeyenetworks.com
# Step 2: the user will login at EEN, login, and get redirected back to your application
# Step 3: Your application backend/server request the end user tokens.

# Flask is used to start an HTTP server to act as your application backend.
import json, requests
from flask import Flask, request


# Hostname and port for the HTTP server
hostName            = "127.0.0.1"
port                = 3333

# Enter your OAuth client credentials. For more info see developerv3.eagleeyenetworks.com
# To user the API your appliction needs its own client credentials.
clientId            = "<your clientId"
clientSecret        = "<your clientSecret"

# This method is executing step 3.
def getTokens(code):
    url = "https://auth.eagleeyenetworks.com/oauth2/token?grant_type=authorization_code&scope=vms.all&code="+code+"&redirect_uri=http://"+hostName + ":" + str(port)
    response = requests.post(url, auth=(clientId, clientSecret))
    return response.text


app = Flask(__name__)

# If a user visits localhost:3333 this method will be called. This method is called in 2 cases:
# 1) For step 1, in this case a link is given to rediret the user to auth.eagleeyenetworks.com
# 2) Handling users that are redirected from auth.eagleeyenetworks.com
@app.route('/')
def index():
    # This is getting the ?code= querystring value from the HTTP request.
    code = request.args.get('code')

    if (code):
        # Execute Step 2, the user is redirected back to localhost:3333 because of the "&redirect_uri="
        # With the CODE this backend can request the actual access_token and refresh_token
        # For demo purposes the results are printed to the console, on production never show the refresh_token in the browser.
        oauthObject = getTokens(code)
        print(oauthObject);
        return "You are logged in"
    else:
        # Executing step 1, a link is generated to redirect the user to auth.eagleeyenetworks.com
        endpoint            = "https://auth.eagleeyenetworks.com/oauth2/authorize"
        requestAuthUrl      = endpoint+"?client_id="+clientId+"&response_type=code&scope=vms.all&redirect_uri=http://"+hostName + ":" + str(port)

        return "<a href='"+requestAuthUrl+"'>Login with Eagle Eye Networks</a>"

# Start the HTTP server
if __name__ == '__main__':
    app.run(host=hostName, port=port)

Logging in

Introduction

Phase 1: Granting access to a third-party app

🚧
Important

📘
Note

Before you begin

Procedure

🚧
Important

🚧
Important

Phase 2: Machine to machine (M2M) authentication

M2M Authentication with an expiring refresh token

🚧
Important

📘
Notes

M2M authentication using non-rotating permanent refresh tokens

📘
Please Note

🚧
Important

Example script for implementing OAuth

Introduction

Phase 1: Granting access to a third-party app

🚧Important

📘Note

Before you begin

Procedure

🚧Important

🚧Important

Phase 2: Machine to machine (M2M) authentication

M2M Authentication with an expiring refresh token

🚧Important

📘Notes

M2M authentication using non-rotating permanent refresh tokens

📘Please Note

🚧Important

Example script for implementing OAuth

🚧
Important

📘
Note

🚧
Important

🚧
Important

🚧
Important

📘
Notes

📘
Please Note

🚧
Important