User authentication via dealer accounts

Goal

Within Eagle Eye CameraManager two categories of users exists:

  • End users which can add cameras, view live video, watch recordings or get motion detection events.
  • Dealer Dashboard admin users which can create 'end users', configure the subscription and delete 'end users".

By default, the Dealer Dashboard admin users cannot login as an End Users. Only the end user can do that with its own email and password which are generally unknown to the dealer.
Eagle Eye CameraManager is a Cloud Video Platform which can be used for by API partners, which have their own user database with own email and passwords. Those partners prefer not to use the the Eagle Eye CameraManager end user authentication mechanism.

The goal of this guide is to authenticate a user by generating an access token through Dealer Dashboard credentials. This can be used by logging in the user on our system after the Dealer Dashboard admin user has authenticated himself.

Assumptions

This guide assumes that the reader has basic knowledge of the following technologies/systems:

Reader is familiar with getting data from a REST API.

  • JSON data structures.
  • Access to Dealer Dashboard.
  • You are an API partner who prefers to use your own authentication method.
  • The Dealer module "Generate Access Token" needs to be enabled and can only be enabled by Eagle Eye CameraManager support team. If you are interested in using this, please contact support.
  • The Dealer Dashboard admin user must have the "Generate access token" permission. This permission is only visible after the "Generate Access Token" module has been enabled.

Process

Authenticating as an 'end user' via a 'Dealer Dashboard 'admin user' with the following process:

Authenticate via the REST API with a dealer dashboard admin user. You will get an access_token for authentication.
Search the end user userId and account Id.
Use the /resellers/self/accounts/{accountId}/users/{userId}/token to get the end user access token.
You will get a different access_token.

Authenticate

1. Get your API key

Request your API key from https://dealer.cameramanager.com. The key will consist of 2 parts, an ID and a SECRET. For example, the ID can be "key" with the secret "qwertyuiopasdfghjklzxcvbnm12345".

At this moment we have to enable this key for provisioning purposes manually. Please contact our support with a request for this and supply the API key details.

2. Login

Add your API key to the authorization header with Basic Auth. Set header "Authorization" with the ID and SECRET in this format: "Basic :" with the ":" encoded in Base64.

For example: "Basic Y2FtZXJhbWFuYWdlci50ZXN0OnF3ZXJ0eXVpb3Bhc2RmZ2hqa2x6eGN2Ym5tMTIzNDU="

The response will include an access_token which can be used with the other API calls. In case the access_token expires, the refresh_token can be used to obtain a new access_token.

http://rest.cameramanager.com/oauth/token?grant_type=password&scope=write&username=<username>&password=<password>
Headers HTTP POST:
Accept application/json
Authorization Basic Y2FtZXJhbWFuYWdlci50ZXN0OnF3ZXJ0eXVpb3Bhc2RmZ2hqa2x6eGN2Ym5tMTIzNDU=
  
Response:
{
    "access_token": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:10003",
    "token_type": "bearer",
    "refresh_token": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:10003",
    "expires_in": 43199,
    "scope": "write"
}

3. Search for a user via email address

If you want to search for a user via email address you can use the following:

  • If you are a distributor, perform the following request: /resellers/all/accounts/all/users?email={0}
  • If you are a reseller, perform the following request: /resellers/self/accounts/all/users?email={0}
    You can replace the {0} with your email address.

4. Get new access_token via refresh token

In case your access_token is expired you can login again using the credentials (email and password). However, this requires your user to login very often which is not user friendly. You can locally store the credentials but this is not recommended for security reasons, in this case you can store the refresh_token and use this to get a new access_token. The access_token can be used again to use the API. The refresh_token will work until the user logs out.

https://rest.cameramanager.com/oauth/token?grant_type=refresh_token&scope=write&refresh_token=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:10003
Headers HTTP POST:
Accept application/json
Authorization Basic Y2FtZXJhbWFuYWdlci50ZXN0InF3ZXJ0eXVpb3Bhc2RmZ2hqa2x6eGN2Ym5tMTIzNDU=
 
Response:
{
    "access_token": "bbbbbbbb-bbbbb-bbbbb-bbbbb-bbbbbbbbbbbbb:10003",
    "token_type": "bearer",
    "refresh_token": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:10003",
    "expires_in": 43199,
    "scope": "write"
}

5. Generate an access_token for the end user

Perform the token API call in order to generate an access token for the end user (see token generation API page for details). If you are a reseller, use the /resellers/self/ to search for all accounts. If you are a distributor with multiple resellers, use /resellers/all/ to search in multiple resellers.

https://rest.cameramanager.com/rest/v2.2/resellers/self/accounts/54321/users/12345/token
Headers HTTP POST:
Accept application/json
Authorization Bearer aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa:10003
  
Response:
{
    "access_token": "cccccccc-cccc-cccc-cccc-cccccccccccc:10003",
    "token_type": "bearer",
    "expires_in": 0,
    "scope": "read"
}

This token can now be used to authenticate on behalf of the specified user. It is no longer needed to perform the login API call for the user.