Versions Compared

Old Version 13

changes.mady.by.user Jan Mucha (Unlicensed)

Saved on

compared with

New Version Current

changes.mady.by.user Jan Mucha (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...


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 applicationsuse cases.

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.

...

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.

    Image Modified

  2. Click on OAuth2 Application.

    Image Modified

  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:

...


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

Code Block
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 that 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:

  • Code Block
    languagejson
    {"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.

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

Parameter

Description

access_token

Existing token to delete.

Answer in JSON format:

Code Block
languagejson
{"success":true,”message”:”Info message”}

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

User permissions for OAuth2

The system distinguishes between full access and partial access users whose view may be restricted. If you use Oauth2 authorization, the data obtained through the API corresponds to the access rights of the user. If you want to ensure full visibility, use an account with full access rights when authorizing OAuth2 or generate a user access token.

...