OAuth login panel + refresh token

Goal

The goal of this guide is to authenticate the "Authorization code" grant type. This can be used to connect a CameraManager user with a third party system. First the user will login via the standard OAuth login page provided by Eagle Eye Networks CameraManager. Second, a refresh_token can be requested to prevent the user from logging in again. Refresh tokens should not be used in the browser, only in the partner's backend.

Assumptions

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

Reader is familiar with getting data from a REST API
JSON data structures

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 "cameramanager.test" with the secret "qwertyuiopasdfghjklzxcvbnm12345".

2. Request login screen

Request the login screen via the following URL. You can request this via the browser. The {client_id} value should be the ID which is provided in the API key, always ensure that your SECRET remains private.

https://rest.cameramanager.com/oauth/authorize?scope=write&client_id={clientId}&response_type=code&redirect_uri={URI_with_http(s)://}

Note:

This request can be made as HTTP POST or HTTP GET, so also directly from the browser.
Following redirects should be enabled
The redirect_uri should include a protocol https:// or http://

For example:
https://rest.cameramanager.com/oauth/authorize?scope=write&client_id=cameramanager.test&response_type=code&redirect_uri=https://example.com

3. Login to login screen

When you are not logged in yet, the user will be presented with following screen. If the user has not authorized your application yet, he will be presented with following screen:

After login, the user is redirected to the redirect_uri with an additional "code" parameter. This code can later be used to get the access_token and refresh_token. The browser will be redirected to the following page: <redirect_uri>?code=AbCdEf.

For example: https://example.com/?code=AbCdEf.

4. Request customer tokens

With the CODE you can request an access_token and refresh_token with the following API call.

Make sure you add the "Accept application/json" header to the HTTP POST request
Make the redirect_uri parameter is the same as the previous request, otherwise the request will fail
Make sure you perform this API call with your application server, not in the browser. If you do this API call in the browser you will expose your API Key and the customer refresh_token.
The Authorization header can use basic auth, encode your <client_id>: with base64.
The returned access_token can be used for accessing the user data, for example to get a camera overview of get a recording.

https://rest.cameramanager.com/oauth/token?grant_type=authorization_code&scope=read&code=AbCdEf&redirect_uri=https%3A%2F%2Fexample.com
Headers HTTP POST:
Accept application/json
Authorization Basic Y2FtZXJhbWFuYWdlci50ZXN0InF3ZXJ0eXVpb3Bhc2RmZ2hqa2x6eGN2Ym5tMTIzNDU=
 
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"
}

5. 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. This new 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"
}

6. Logout

To logout, call the following API call which will delete the access_token and refresh_token. The API call must be performed as a DELETE HTTP request.

http://rest.cameramanager.com/rest/v2.0/users/self/tokens/current
Headers HTTP DELETE:
Accept application/json
Authorization Bearer bbbbbbbb-bbbbb-bbbbb-bbbbb-bbbbbbbbbbbbb:10003
 
Response:
HTTP 200 OK