This article applies as of PRTG 25.4.112
The REST Custom v2 sensor now supports session-based authentication. Use session-based authentication for REST APIs that require a login to retrieve a session token or cookie before making further requests. The sensor performs a new login with each sensor scan.
This article shows you how to configure the sensor using some real-world examples. We tested the sensor with a Veeam Backup Enterprise Manager, Veeam Backup & Replication, Synology File Station, and a Redfish environment. These examples cover common use cases and should help you configure session-based authentication for similar APIs in your environment. Adjust the URLs, headers, and paths as needed based on the API documentation of your target system.
For more information about the REST API credentials in the device settings, see the PRTG Manual: Device Settings.
In this article:
Veeam Backup Enterprise Manager
This example shows you how to monitor job data from the Veeam Backup Enterprise Manager REST API. The API returns a session token in the response header after a login request.
Device credentials for Veeam Backup Enterprise Manager REST API
| Setting | Description |
|---|---|
| Authentication Method | Select Session-based authentication. |
| User Name | Enter the user name for access to the REST API. |
| Password | Enter the password for access to the REST API. |
| Login Path | Enter the path for the login request, for example, https://<host>:9398/api/sessionMngr/?v=v1_5. ℹ Make sure to substitute the placeholder <host>. |
| Authentication Header | Select Include header for basic authentication (default). |
| Login Request Method | Select POST. |
| POST Data | Enter the data to POST to the login path. |
| Custom Headers | Enter any custom headers or leave this field empty. |
| Login Result Type | Select Header (default). |
| Login Header Name | Enter a login header name, for example, X-RestSvcSessionId. |
| Token Type | Select Via header or Via cookie. |
| Header Name | This setting is only available if you select Via header above. Enter a header name, for example, X-RestSvcSessionId. |
| Cookie Name | This setting is only available if you selected Via cookie above. Enter a cookie name, for example, X-RestSvcSessionId. |
Sensor settings for REST Custom v2 with Veeam Backup Enterprise Manager REST API
Specific Sensor Settings
| Setting | Description |
|---|---|
| Request URL | Enter the URL that you want to request. For example, enter https://<host>:9398/api/jobs. ℹ Make sure to substitute the placeholder <host>. |
| Request Method | Select the HTTP request method that you want to use to request the URL. |
| Custom HTTP Headers | Specify custom HTTP headers that the REST API request of the sensor contains or leave this field empty. |
| Timeout (Sec.) | Enter a timeout value in seconds. |
| Content Type | Select the type of the content that the sensor queries. |
| Custom Sensor Message | Enter a custom sensor message or leave this field empty. |
Channel Settings
| Setting | Description |
|---|---|
| Channel #1 JSONPath/XPath | Enter the JSONPath or XPath that you want to monitor. For example, enter length($.Refs). |
| Channel #1 Name | Enter a name to identify the channel. For example, enter Total Jobs. |
| Channel #1 Value Type | Select the value type that the channel displays. |
| Channel #1 Unit | Select the unit of the value that this channel monitors. |
| Channel #2-#10 | Select if you want to add more channels. |
| Channel #2 JSONPath/XPath | Enter the JSONPath or XPath that you want to monitor. For example, enter length($.Refs[?(@.Name=="General Backup")]). |
| Channel #2 Name | Enter a name to identify the channel. For example, enter General Backup Jobs. |
| Channel #2 Value Type | Select the value type that the channel displays. |
| Channel #2 Unit | Select the unit of the value that this channel monitors. |
Veeam Backup & Replication
This example shows you how to monitor job data from the Veeam Backup & Replication REST API. The API returns a session token in the response header after a login request.
Device credentials for Veeam Backup & Replication REST API
| Setting | Description |
|---|---|
| Authentication Method | Select Session-based authentication. |
| User Name | Enter the user name for access to the REST API. |
| Password | Enter the password for access to the REST API. |
| Login Path | Enter the path for the login request. For example, enter https://<host>:9419/api/oauth2/token. ℹ Make sure to substitute the placeholder <host>. |
| Authentication Header | Select Do not include an authentication header. |
| Login Request Method | Select POST. |
| POST Data | Enter the data to POST to the login path. For example, enter grant_type=password&username=%restusername&password=%restpassword&refresh_token =&code=&use_short_term_refresh=&vbr_token=. |
| Custom Headers | Enter any custom headers or leave this field empty. For example, enter accept: application/json x-api-version: 1.2-rev0 Content-Type: application/x-www-form-urlencoded |
| Login Result Type | Select JSON. |
| JSONPath | Enter the JSONPath to the session key value in the login response. For example, enter $.access_path. |
| Token Type | Select Bearer (default). |
Sensor settings for REST Custom v2 with Veeam Backup & Replication REST API
Specific Sensor Settings
| Setting | Description |
|---|---|
| Request URL | Enter the URL that you want to request. For example, enter https://<host>:9419/api/v1/jobs/states. ℹ Make sure to substitute the placeholder <host>. |
| Request Method | Select the HTTP request method that you want to use to request the URL. |
| Custom HTTP Headers | Specify custom HTTP headers that the REST API request of the sensor contains or leave this field empty. |
| Timeout (Sec.) | Enter a timeout value in seconds. |
| Content Type | Select the type of the content that the sensor queries. |
| Custom Sensor Message | Enter a custom sensor message or leave this field empty. |
Channel Settings
| Setting | Description |
|---|---|
| Channel #1 JSONPath/XPath | Enter the JSONPath or XPath that you want to monitor. For example, enter $.data.0.lastResult. |
| Channel #1 Name | Enter a name to identify the channel. For example, enter Job Status. |
| Channel #1 Value Type | Select the value type that the channel displays. |
| Channel #1 Unit | Select the unit of the value that this channel monitors. |
| Channel #2-#10 | Select if you want to add more channels. |
Synology File Station
This setup connects to a Synology File Station API, which authenticates via a login cookie returned from a GET request. The example retrieves and filters shared folders.
Device credentials for Synology File Station REST API
| Setting | Description |
|---|---|
| Authentication Method | Select Session-based authentication. |
| User Name | Enter the user name for access to the REST API. |
| Password | Enter the password for access to the REST API. |
| Login Path | Enter the path for the login request. For example, enter https://<host>:5001/webapi/auth.cgi?api=SYNO.API.Auth&method=login&version=3&account=%restusername&passwd =%restpassword&session=FileStation. ℹ Make sure to substitute the placeholder <host>. |
| Authentication Header | Select Do not include an authentication header. |
| Login Request Method | Select GET. |
| Custom Headers | Enter any custom headers or leave this field empty. |
| Login Result Type | Select Cookie. |
| Login Cookie Name | Enter the cookie name to get the session key value in the login response. For example, enter id. |
| Token Type | Select Via cookie. |
| Cookie Name | Enter the cookie name to use for authorization. For example, enter id. |
Sensor settings for REST Custom v2 with Synology File Station REST API
Specific Sensor Settings
| Setting | Description |
|---|---|
| Request URL | Enter the URL that you want to request. For example, enter https://<host>:5001/webapi/query.cgi?api=SYNO.FileStation.List&version=2&method=list_share. ℹ Make sure to substitute the placeholder <host>. |
| Request Method | Select the HTTP request method that you want to use to request the URL. |
| Custom HTTP Headers | Specify custom HTTP headers that the REST API request of the sensor contains or leave this field empty. |
| Timeout (Sec.) | Enter a timeout value in seconds. |
| Content Type | Select the type of the content that the sensor queries. |
| Custom Sensor Message | Enter a custom sensor message or leave this field empty. |
Channel Settings
| Setting | Description |
|---|---|
| Channel #1 JSONPath/XPath | Enter the JSONPath or XPath that you want to monitor. For example, enter count($.data.shares[?(@.name=="docker")]). |
| Channel #1 Name | Enter a name to identify the channel. For example, enter Docker Shares. |
| Channel #1 Value Type | Select the value type that the channel displays. |
| Channel #1 Unit | Select the unit of the value that this channel monitors. |
| Channel #2-#10 | Select if you want to add more channels. |
| Channel #2 JSONPath/XPath | Enter the JSONPath or XPath that you want to monitor. For example, enter count($.data.shares). |
| Channel #2 Name | Enter a name to identify the channel. For example, enter Total Shares. |
| Channel #2 Value Type | Select the value type that the channel displays. |
| Channel #2 Unit | Select the unit of the value that this channel monitors. |
Redfish
This example uses a Redfish REST API. It creates a session with a POST request and returns a token in the response header. We used a Fujitsu PRIMERGY device for the implementation of this example.
Device credentials for Redfish REST API
| Setting | Description |
|---|---|
| Authentication Method | Select Session-based authentication. |
| User Name | Enter the user name for access to the REST API. |
| Password | Enter the password for access to the REST API. |
| Login Path | Enter the path for the login request. For example, enter /redfish/v1/SessionService/Sessions. |
| Authentication Header | Select Do not include an authentication header. |
| Login Request Method | Select POST. |
| POST Data | Enter the data to POST to the login path. You can use placeholders, for example, {"UserName": "%restusername", "Password": "%restpassword"}. |
| Custom Headers | Enter any custom headers. For example, enter Content-Type: application/json. |
| Login Result Type | Select Header (default). |
| Login Header Name | Enter a login header name, for example, X-Auth-Token. |
| Token Type | Select Via header. |
| Header Name | Enter a header name, for example, X-Auth-Token. |
Sensor settings for REST Custom v2 with Redfish REST API
Specific Sensor Settings
| Setting | Description |
|---|---|
| Request URL | Enter the URL that you want to request. For example, enter https://%host//redfish/v1/Systems/0. |
| Request Method | Select the HTTP request method that you want to use to request the URL. |
| Custom HTTP Headers | Specify custom HTTP headers that the REST API request of the sensor contains or leave this field empty. |
| Timeout (Sec.) | Enter a timeout value in seconds. |
| Content Type | Select the type of the content that the sensor queries. |
| Custom Sensor Message | Enter a custom sensor message or leave this field empty. |
Channel Settings
| Setting | Description |
|---|---|
| Channel #1 JSONPath/XPath | Enter the JSONPath or XPath that you want to monitor. For example, enter $.ProcessorSummary.Count. |
| Channel #1 Name | Enter a name to identify the channel. For example, enter CPU Count. |
| Channel #1 Value Type | Select the value type that the channel displays. |
| Channel #1 Unit | Select the unit of the value that this channel monitors. |
| Channel #2-#10 | Select if you want to add more channels. |
| Channel #2 JSONPath/XPath | Enter the JSONPath or XPath that you want to monitor. For example, enter $.MemorySummary.TotalSystemMemoryGiB. |
| Channel #2 Name | Enter a name to identify the channel. For example, enter Memory Size. |
| Channel #2 Value Type | Select the value type that the channel displays. |
| Channel #2 Unit | Select the unit of the value that this channel monitors. |
