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 use cases.
The Oauth2 protocol can also be used to obtain a token. 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.
Click on the user icon in the upper right corner and select an option </> API.
Click on OAuth2 Application.
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.
When creating an application, you need to enter the following information:
name - any name, e.g. "My application"
application description - any description
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 |
|---|---|
| Identifies the client application |
| Comma-separated list of required rights. Possible rights are:
|
| URL to which the authorization code should be sent. It must be the same as the URL allowed in the client application definition. |
| 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.
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 |
|---|---|
| Identifies the client application |
| 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). |
| 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. |
| Parameter specifying the authorization method. The following options are available:
This is the exchange of the authorization code from the previous step for an access 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 |
| Existing token to delete. |
Answer in JSON format:
{"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.