Guides
Getting startedVisit een.comMy Application/Login

Logging in

Suggest Edits

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

  • Create your application in the Eagle Eye Developer Portal and obtain your client ID and client secret. For more instructions, see the Client Credentials page.
  • Add your application's redirect URI to the OAuth whitelist. You must the protocol (https\:// or http\://) in the entry. 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

  1. Make the request as HTTP POST or HTTP GET, or go to your browser of choice.
  2. 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 ensure 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.

  1. 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.

  1. Use this code to get the access token and refresh token. To do this, make an HTTP POST request to "https://auth.eagleeyenetworks.com/oauth2/token" with the following parameters:
  • grant_type: "authorization_code"
  • scope: "vms.all"
  • code: The code parameter from the previous step
  • redirect_uri: The redirect URI with http(s)://

You must authenticate the request with your Client Credentials. The Authorization header uses basic access authentication with the client_id and client_secret serving as the username and password. The client_id and client_secret must be encoded with Base64 and joined by a single colon. In addition, the code must be used within 5 minutes of being generated or it will expire.

You can see an example of this request below:

curl --request 'POST' \
  --url 'https://auth.eagleeyenetworks.com/oauth2/token' \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'authorization: Y2xpZW50SWQ6Y2xpZW50U2VjcmV0' \
  --data '
{
  "grant_type": "authorization_code",
  "scope": "vms.all",
  "code": "{code}",
  "redirect_uri": "{URI with http(s)://}"
}
'

import requests

url = "https://auth.eagleeyenetworks.com/oauth2/token"
data = {
  "grant_type": "authorization_code",
  "scope": "vms.all",
  "code": "{code}",
  "redirect_uri": "{URI with http(s)://}"
}
headers = {
    "accept": "application/json",
    "content-type": "application/x-www-form-urlencoded"
}
response = requests.post(
  url,
  headers=headers,
  auth=(
    'CLIENT_ID',
    'CLIENT_SECRET'
  ),
  data=data
)

print(response.text)

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"io"
)

func main() {

    url := "https://auth.eagleeyenetworks.com/oauth2/token"
    data := url.Values{}
    data.Set("grant_type", "authorization_code")
    data.Set("scope", "vms.all")
    data.Set("code", code)
    data.Set("redirect_uri", fmt.Sprintf("http://%s:%d", hostName, port))


    req, _ := http.NewRequest("POST", url, bytes.NewBufferString(data.Encode()))

    req.Header.Add("accept", "application/json")
	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
    req.SetBasicAuth(clientId, clientSecret)

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)

    fmt.Println(string(body))

}

🚧

Important

  • Make sure to add the accept application/json header to the HTTP POST request.
  • The content-type header should be set to application/x-www-form-urlencoded.
  • 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.
  • All parameters must be sent in the request body as JSON. Query parameters are not supported.

In response, you'll recieve an access token and a refresh token. The access token can be used to authenticate API calls while the refresh token can be stored for future use. 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.

Example Response:

{
    "access_token": "eyJraWQiOiI2ODYxYjBjYS0wZjI2LTExZWQtODYxZC0wMjQyYWMxMjAwMDIiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjYTBmNjFhYiIsImF1ZCI6InZtcy5hcGkiLCJpc3MiOiJ2bXMuYXV0aC52MSIsInZtc19hY2NvdW50IjoiMDAwMDExMDYiLCJleHAiOjE2NjAzNjA0ODksImlhdCI6MTY2MDMxNzI4OSwianRpIjoiODJlNWMyMDQ1OTM1OTczNGYyOTU4NjlkZDhlYzIyMDMiLCJjbGllbnRfaWQiOiJCTVRPLVRFU1QiLCJ2bXNfY2x1c3RlciI6ImMwMDAifQ.JuUiozX0XMKz0kuFJTGsNFRdxOKNV4R6iRW8t6N-FpElU4sWBLhyioIot3dV2GFnHWpY5wzdFWuwVxuSvYRwhPGs6sYt4Uo0pWsrI6a9WylyavacjSmLuljdnplUzKuoB3BzohCrQGCUmiMFJ8eA4jNZnViuQ7ouKRoM4mbTSdwy_YUoNm4F7GDBiHp6TEoMFscUDlWzC-GJwVMklRGAAw_9OTTl-CGWt-CngqL1K-2Qt-3iS0WY1Jpal3-YMlJ1FVTDDuCgVIluemaH2g7ScEOM5vEnpj31H_6Gu7R9NB5CDzLaEDm2MHRJThId1-3kyhreG3Ux-WV2TAOzGbLnkg",
    "expires_in": 43198,
    "httpsBaseUrl": {
        "hostname": "api.c001.eagleeyenetworks.com",
        "port": 443
    },
    "refresh_token": "w1P0nwA7NEZmo5tEd76cco3y5bi4Js6QNgZsXnFNBDRepnJmA2F73tGJ4G_eA0WttI_8xsovsFLvd5uOUayqrNwu7PZ1SH0DAWVZ3",
    "scope": "vms.all",
    "token_type": "Bearer"
}

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.

  1. Log in using the refresh token.

📘

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, 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' \
--header 'Accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0' \
--data '
{
    "grant_type": "refresh_token",
    "scope": "vms.all",
    "refresh_token": "P1m_7oFP2Ful4yVGh5Z9QcQlGygiMaz0uah3QvqUbZpfufBSmpr9P6dPvlBP_1EhKS1WjyUcFGxQZrEewn62X1Og0Ww1ns3wA0ah5jJHowabYlHoYS0DAg7QUE6_mZFT"
}
'

import requests

url = "https://auth.eagleeyenetworks.com/oauth2/token"
data = {
    "grant_type": "refresh_token",
    "scope": "vms.all",
    "refresh_token": "P1m_7oFP2Ful4yVGh5Z9QcQlGygiMaz0uah3QvqUbZpfufBSmpr9P6dPvlBP_1EhKS1WjyUcFGxQZrEewn62X1Og0Ww1ns3wA0ah5jJHowabYlHoYS0DAg7QUE6_mZFT"
}
headers = {
    "accept": "application/json",
    "content-type": "application/x-www-form-urlencoded"
}
response = requests.post(
    url,
    headers=headers,
    auth=(
        'CLIENT_ID',
        'CLIENT_SECRET'
    ),
    data=data
)

print(response.text)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
	"net/url"
    "io"
)

func main() {

    url := "https://auth.eagleeyenetworks.com/oauth2/token"
    data := url.Values{}
    data.Set("grant_type", "refresh_token")
    data.Set("scope", "vms.all")
    data.Set("refresh_token", "P1m_7oFP2Ful4yVGh5Z9QcQlGygiMaz0uah3QvqUbZpfufBSmpr9P6dPvlBP_1EhKS1WjyUcFGxQZrEewn62X1Og0Ww1ns3wA0ah5jJHowabYlHoYS0DAg7QUE6_mZFT")

    req, _ := http.NewRequest("POST", url, bytes.NewBufferString(data.Encode()))

    req.Header.Add("accept", "application/json")
	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
    req.SetBasicAuth(clientId, clientSecret)

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)

    fmt.Println(string(body))
}

Response:

{
    "access_token": "eyJraWQiOiI2ODYxYjBjYS0wZjI2LTExZWQtODYxZC0wMjQyYWMxMjAwMDIiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjYTBmNjFhYiIsImF1ZCI6InZtcy5hcGkiLCJpc3MiOiJ2bXMuYXV0aC52MSIsInZtc19hY2NvdW50IjoiMDAwMDExMDYiLCJleHAiOjE2NjAzNjA0ODksImlhdCI6MTY2MDMxNzI4OSwianRpIjoiODJlNWMyMDQ1OTM1OTczNGYyOTU4NjlkZDhlYzIyMDMiLCJjbGllbnRfaWQiOiJCTVRPLVRFU1QiLCJ2bXNfY2x1c3RlciI6ImMwMDAifQ.JuUiozX0XMKz0kuFJTGsNFRdxOKNV4R6iRW8t6N-FpElU4sWBLhyioIot3dV2GFnHWpY5wzdFWuwVxuSvYRwhPGs6sYt4Uo0pWsrI6a9WylyavacjSmLuljdnplUzKuoB3BzohCrQGCUmiMFJ8eA4jNZnViuQ7ouKRoM4mbTSdwy_YUoNm4F7GDBiHp6TEoMFscUDlWzC-GJwVMklRGAAw_9OTTl-CGWt-CngqL1K-2Qt-3iS0WY1Jpal3-YMlJ1FVTDDuCgVIluemaH2g7ScEOM5vEnpj31H_6Gu7R9NB5CDzLaEDm2MHRJThId1-3kyhreG3Ux-WV2TAOzGbLnkg",
    "expires_in": 25734,
    "httpsBaseUrl": {
        "hostname": "api.c001.eagleeyenetworks.com",
        "port": 443
    },
    "refresh_token": "Mp4k-iSQYwZ3074_e5LUJ2A01BBm5QZ6H5hE_PrGsK5edxptWsgpXQ2QxfVwrqi8MC6jhdY72y5rWA1-5znkb_QSqfF0GXLYz9m1DrUYPQ2dJRouBrK2lv5xYZerV-7D",
    "scope": "vms.all",
    "token_type": "Bearer"
}

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 access tokens requested by that refresh token. If the same user completes the code authentication again by entering a username and password on the Eagle Eye login page, a new refresh token and access token set will be created.

🚧

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.

OAuth Implementation Example

The following recipe demonstrates how to implement OAuth2 in multiple programming languages.

🔐
OAuth Authentication
Open Recipe

Updated 2 months ago