Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 16 Next »

What is good for?


There are two ways to obtain an authorization token. The first option is to create a token in the user interface. This option is the simplest and is recommended for most API applications.

The Oauth2 protocol can also be used to obtain a token. The steps described below describe the procedure for obtaining an authorization token using OAuth2. We recommend using one of the available libraries to implement OAuth2. More information and an introduction to OAuth2.

About OAuth2

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

Please mind, that examples in code-styled blocks can contain a different provider URL (basically system2.netrex.cz).

If you have an account under another provider, you have to change it according to yours provider URL (e.g. cloud.camstreamer.com)

\uD83D\uDCD8 Creating a client application

First, we will create a new OAuth2 application. The OAuth2 application allows authorization to the API using any owner or guest account. The client application management interface is available after logging in to your account.

  1. Click on the user icon in the upper right corner and select an option </> API.

  2. Click on OAuth2 Application.

  3. The OAuth2 application defines the requester for access to the application interface. Only full access accounts can create the application. The application can be used to authorize any system account.

  4. When creating an application, you need to enter the following information:

    1. name - any name, e.g. "My application"

    2. application description - any description

    3. list of redirect URLs - The URL to which the user is redirected after authorization


After OAuth2 is created, the application is generated:

  • client_id - unique application identifier

  • client_secret - application key

We recommend creating a new client application for each integration.

Obtaining an authorization code

To obtain an authorization code, which can be further exchanged for an access token,  the endpoint https://system2.netrex.cz/oauth2/auth is used.

POST: https://system2.netrex.cz/oauth2/auth/?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&scope=read,write


Request parameters:

Parameter

Description

client_id

Identifies the client application

scope

Comma-separated list of required rights. Possible rights are:

  • read

  • write

  • liveview

  • audiotransmit

  • liveview_ptz

  • liveview_light

  • liveview_audioclip

  • recordings

  • recordings_delete

  • events

redirect_url

URL to which the authorization code should be sent. It must be the same as the URL allowed in the client application definition.

state

Optional security parameter that is passed back to redirect_url without change along with the authorization code.

First, you are redirected to the portal login screen, and after logging in to your CamStreamer Cloud account, a dialog is displayed asking you to grant access to the client application. After confirming/rejecting the dialog, the redirect_url is redirected and the "code" parameter with the authorization code or the "error" parameter with the reason for the error is added to the GET parameters ("access_denied" if the user has rejected the access request).
If the "state" parameter was specified in the request, it will be added to the redirection as well.

Obtaining an access token

The endpoint https://system2.netrex.cz/oauth2/token is used to obtain the access token and possibly also the refresh token.

POST:
https://system2.netrex.cz/oauth2/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=CALLBACK_URL

Parameter

Description

client_id

Identifies the client application

client_secret

The secret key of the client application, with the use of which it is possible to obtain permanent access to the API (access and refresh tokens).
Without this parameter, only temporary access is granted (ie olny access token). Note the client_secret parameter cannot be used where there is a risk of it leaking out. For example, it is not possible to use it in JavaScript applications.

redirect_url

Ont of the redirect URLs listed in the client application definition. In this step, it only serves as an additional security feature an no futher redirection occurs.

grant_type

Parameter specifying the authorization method. The following options are available:

  • auth_code

This is the exchange of the authorization code from the previous step for an access token.

  • refresh_token

This is a renewal or exchange for a new, access token for the next period.


Possible answers in JSON format:

  • {"access_token":"ACCESS_TOKEN","expires_in":3600,"refresh_token":"1234"}

- unlimited time access to the API. When the access token expires, a new one can be obtained by refreshing the token. For this type of access, you must use client_secret in the query.

  • {"access_token":"ACCESS_TOKEN","expires_in":3600} - One-time access to the API, canceled when the access token expires.

  • {"error":"Error message"} - Invalid request or system error.

The obtained ACCESS_TOKEN can be inserted into the header of each Graph API call (“Authorization: Bearer TOKEN”).

Cancel access token

The access token can be canceled at any time in the user interface or using the API. The endpoint https://system2.netrex.cz/oauth2/revoke is used to cancel the access.

POST:
https://system2.netrex.cz/oauth2/revoke?access_token=ACCESS_TOKEN

Parameter

Description

access_token

Existing token to delete.

Answer in JSON format:

{"success":true,”message”:”Info message”}

  • The given access token (even with its refresh token) is canceled.

  • No labels