Authentication API

The REST API uses OAuth 2.0 for authentication and session management. This page will provide some information on how to use Oauth 2.0 with the Eagle Eye CameraManager REST API, but much more information about the protocol is available online (ie. here and here).

The Eagle Eye CameraManager REST API uses Oauth 2.0 for the following actions. 

  • Authorizing a user and retrieving an access token to the API. 
  • Retrieving the session and user ID to be used for the XML based API (The old API)
  • Removing authorization of a user by removing the token from the system. 
{ "swagger": "2.0", "info": { "description": "Cameramanager authentication API", "version": "2.0", "title": "CameraManager authentication" }, "host": "rest.cameramanager.com", "basePath": "/", "responses": { "unauthorized": { "description": "You are not authenticated. Please authenticate and try again.", "schema": { "$ref": "#/definitions/OAuth2Error" } }, "notAcceptableError": { "description": "The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.", "schema": { "$ref": "#/definitions/Error" } }, "internalServerError": { "description": "Something went wrong in the server. Please try again.", "schema": { "$ref": "#/definitions/Error" } } }, "paths": { "/oauth/token": { "post": { "tags": [ "Authentication" ], "summary": "Get access token", "operationId": "getAccessToken", "consumes": [ "application/json" ], "produces": [ "*/*" ], "parameters": [ { "name": "grant_type", "in": "query", "type": "string", "enum": [ "password", "client_credentials", "authorization_code" ], "description": "Type of OAuth flow.", "required": true }, { "name": "scope", "in": "query", "type": "string", "enum": [ "write", "read" ], "description": "Scopes that are requested for this token.", "required": true }, { "name": "username", "in": "query", "type": "string", "description": "Username of the user trying to login (Password flow only)", "required": false }, { "name": "password", "in": "query", "type": "string", "enum": [ "write", "read" ], "description": "Password of the user trying to login (Password flow only)", "required": false }, { "name": "client_id", "in": "query", "type": "string", "description": "Id of the client requesting the token (Authorization code flow only)", "required": false }, { "name": "client_secret", "in": "query", "type": "string", "description": "Client secret, should not be visible to users (Authorization code flow only)", "required": false }, { "name": "code", "in": "query", "type": "string", "description": "Authorization code acquired with /oauth/authorize request (Authorization code flow only)", "required": false }, { "name": "redirect_uri", "in": "query", "type": "string", "description": "URI to client server to process/save token (Authorization code flow only)", "required": false } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/OAuth2AccessToken" } }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } } } }, "/oauth/authorize": { "post": { "tags": [ "Authentication" ], "summary": "Get authorization code", "operationId": "getAuthorizationCode", "produces": [ "text/html" ], "parameters": [ { "name": "scope", "in": "query", "type": "string", "enum": [ "camerainfo.read", "camerainfo.write", "livestream.read", "cloudvideo.read", "cloudvideo.write", "cameramanagement.read", "accountinfo.read", "accountmanagement.write" ], "description": "Scopes that are requested for this authorization", "required": false }, { "name": "client_id", "in": "query", "type": "string", "description": "id of the client that is requesting authorization", "required": true }, { "name": "response_type", "in": "query", "type": "string", "enum": [ "code" ], "description": "Specifies the type of authorization grant. Only authorization code type grant is supported.", "required": true }, { "name": "redirect_uri", "in": "query", "type": "string", "description": "URI to the client server that processes the authorization code", "required": true } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" }, "500": { "$ref": "#/responses/internalServerError" } } } }, "/rest/v2.0/users/self/sessions": { "post": { "tags": [ "Authentication" ], "summary": "Create a new session for the authenticated user", "description": "Creates a new session for the authenticated user or partner. The response contains the newly created session ID and the user or partner ID.", "operationId": "createSelfSession", "produces": [ "*/*" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Token has to be passed as value of the Authorization header like 'Bearer [token]'.", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/SessionInfo" } }, "401": { "$ref": "#/responses/unauthorized" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } } } }, "/rest/v2.0/users/self/tokens/current": { "delete": { "tags": [ "Authentication" ], "summary": "Deletes the token of the logged in user.", "description": "Logs out the user by deleting the given authorization token.", "operationId": "deleteSelfToken", "produces": [ "*/*" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Token has to be passed as value of the Authorization header like 'Bearer [token]'.", "required": true, "type": "string" } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "description": "Forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } } } } }, "definitions": { "OAuth2RefreshToken": { "type": "object", "properties": { "value": { "type": "string" } } }, "OAuth2AccessToken": { "type": "object", "properties": { "additionalInformation": { "type": "object" }, "expiration": { "type": "string", "format": "date-time" }, "expired": { "type": "boolean" }, "expiresIn": { "type": "integer", "format": "int32" }, "refreshToken": { "$ref": "#/definitions/OAuth2RefreshToken" }, "scope": { "type": "array", "items": { "type": "string" } }, "tokenType": { "type": "string" }, "value": { "type": "string" } } }, "PartnerSession": { "type": "object", "properties": { "partnerId": { "type": "integer", "format": "int32", "minimum": 0, "description": "The partner ID of the authenticated partner user." }, "accountId": { "type": "integer", "format": "int32", "minimum": 0, "description": "The partner user ID of the authenticated partner user." }, "superPartnerId": { "type": "integer", "format": "int32", "minimum": 0, "description": "The ID of the super partner of the authenticated partner user." } }, "required": [ "partnerId", "accountId" ] }, "Session": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "The session ID to be used to perform API calls." }, "userId": { "type": "integer", "format": "int32", "minimum": 0, "description": "The user ID of the authenticated user." }, "partnerSession": { "$ref": "#/definitions/PartnerSession" } }, "required": [ "sessionId" ] }, "ServerInfo": { "type": "object", "properties": { "serverIp": { "type": "string" }, "httpPort": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 65535 }, "httpsPort": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 65535 } } }, "SessionInfo": { "type": "object", "properties": { "session": { "$ref": "#/definitions/Session" }, "server": { "$ref": "#/definitions/ServerInfo" } } }, "Error": { "type": "object", "description": "Generic error response, modelled after RFC 7807.", "properties": { "code": { "type": "integer", "description": "Error code within the system." }, "title": { "type": "string", "description": "This title is not meant to be shown to users and is not guaranteed to stay the same. Please use the code to parse the error." }, "detail": { "type": "string", "description": "Error details, to help developers detect what went wrong." } }, "required": [ "code", "title" ] }, "OAuth2Error": { "type": "object", "description": "Generic OAuth2 error response when there is something wrong with the OAuth2 authentication. Defined at RFC 6749.", "properties": { "error": { "type": "string", "description": "A single ASCII error code conforming the pattern." }, "error_description": { "type": "string", "description": "Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred." } }, "required": [ "error" ] } } }

Implicit grant

The Implicit grant consists of one single interaction with the Eagle Eye CameraManager REST API. 

The access code can be directly retrieved from the authorize endpoint in the API. The user should be redirected to the `authorize` endpoint with the follow arguments:

  • client_id: The client id provided by Eagle Eye CameraManager that is used to identify the application
  • redirect_uri: A uri where the user is returned after authorizing the request, this uri should parse the returned access code. 
  • response_type: The type of grant that is used, Use "token" for the implicit grant.
  • scope: The access level that is requested with this authorization request. 

The access code is then place is the `token` argument of the redirect_uri and should be extracted/stored in the client. This process has to be repeated when the access code expires. 

Please ensure the API Key client ID is unique for each client using it. Otherwise, your concurrent second token request will fail.
If your client ID is "YourCloudUser", then you can add a unique ID to this, such that: "YourCloudUser-123456789ABCDEF".
Important information about client ID:
It must be a unique alphanumeric([0-9a-zA-Z] in regex) string with a maximum length of 16 characters for that specific client
You can use for example some randomly generated string, a hostname or a unique device serial number, for example, "123456789ABCDEF" or the IMEI of a phone.
You must generate a unique clientId using this template: uniqueClientId = {clientId}-{uniqueId}. The hyphen is important.
It is also important to use the same uniqueClientId for any subsequent use of any token generated with the unique value. The main example of this is when refreshing a token.

Authentication API YAML specification
swagger-authentication.yaml