DeskAlerts 11 REST API guide

Overview

DeskAlerts 11 RESTful API web services allow you to perform any actions that you can do manually, so you can integrate DeskAlerts with any scripts or third-party applications that support  RESET API. DeskAlerts API calls require session management to persist security cookies between requests. You need to authenticate with your DeskAlerts API endpoint and save the antiforgery token and security token cookies. In PowerShell, you can persist session data between requests using -WebSession parameter of the Invoke-WebRequest and Invoke-RestMethod cmdlets, which will be showcased later in this guide.

How to enable Swagger documentation page

You can get a full list of API methods available in DeskAlerts on our swagger documentation page. You can enable Swagger in the configuration file of the frontend service:

1. Navigate to C:\inetpub\wwwroot\DeskAlerts\www\ folder
2. Open appsettings.Production.json in a text editor
3. Change EnableSwaggerInProductionMode parameter to true and save the file
4. Re-cycle the application pool that contains your DeskAlerts frontend service

After this you can access Swagger page by appending /swagger to your DeskAlerts URL (i.e. https://yourdeskalertsserver.com/DeskAlerts/swagger ). If you are using our cloud offering, please ask us to enable Swagger for your cloud instance.

Get the credentials

Current version of DeskAlerts 11 supports 2 types of authentication on the API endpoint:

1. API secret key
2. Admin/publisher credentials

API secret key authentication

API secret key authentication is available in versions 11.4.0.2 and above. If your DeskAlerts server version is older, please use Admin/publisher credentials authentication method or update your server to the latest version. To get the API secret key to go to Settings > API, click checkbox for "Enable API Secret key" option and click save. After this copy the API secret from the API secret field.

With this key make a POST request to api/account/apikey endpoint with this payload in the body 

{
    "key": "Your-Actual-API-Sercret-Key-Here"
}

After this you should receive the security cookies and can start making API calls.

Send an alert in C# using API secret key

Below is a dotnet script that logs in using API secret key, finds a user "John Doe" and sends a pop-up alert to it:

C#

using System.Text;
using System.Text.Json;

class DeskAlertsAPI
{
    private static readonly HttpClient Client = new HttpClient();
    private static readonly string ApiEndpoint = "https://yourdeskalertsserver.com/DeskAlerts/api/";

    static async Task Main(string[] args)
    {
        // Login
        await Login();

        // Search for user "John Doe" and get userId
        string userId = await GetUser("John Doe");

        // Compose and send the alert to "John Doe"
        await SendAlert(userId, "This alert was sent through DeskAlerts 11 REST API to a user John Doe", "DeskAlerts 11 REST API test");
    }

    private static async Task Login()
    {
        var loginData = new
        {
            key = "paste-your-api-key-here"
        };

        var content = new StringContent(JsonSerializer.Serialize(loginData), Encoding.UTF8, "application/json");
        var response = await Client.PostAsync(ApiEndpoint + "account/apikey", content);
        response.EnsureSuccessStatusCode();
    }

    private static async Task<string> GetUser(string name)
    {
        var userData = new
        {
            name = name,
            filterMode = "1"
        };
        var content = new StringContent(JsonSerializer.Serialize(userData), Encoding.UTF8, "application/json");
        var response = await Client.PostAsync(ApiEndpoint + "organization/users", content);
        response.EnsureSuccessStatusCode();
        var responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseBody);
        var result = JsonSerializer.Deserialize<JsonElement>(responseBody);
        return result.GetProperty("data")[0].GetProperty("userId").ToString();
    }

    private static async Task SendAlert(string userId, string message, string title)
    {
        var alertData = new
        {
            body = message,
            title = title,
            skinId = "1",
            recipients = new[] { new { id = userId, type = "User" } }
        };
        var content = new StringContent(JsonSerializer.Serialize(alertData), Encoding.UTF8, "application/json");
        var response = await Client.PostAsync(ApiEndpoint + "publisher/alert/create", content);
        response.EnsureSuccessStatusCode();
    }
}

Admin/publisher credentials

This method is a little less convenient than API secret key authentication, as it requires additional actions for requests and getting credentials. For this authentication method you will need to get the salted version of the password:

1. Open your DeskAlerts login page in Chrome or Edge browser
2. Open Developer Tools (F12)
3. Navigate to Network-> Fetch/XHR tab
4. Enable "Preserve log" option
5. Log in with credentials you would like to authenticate with the API gateway
6. Open the Login method in the list and copy value of the password key, this is your salted password:

Now you have a login and a salted password necessary to authenticate with the API gateway.

Please note that performing API calls on behalf of an admin/publisher counts as a user session, which will log this publisher out of the browser session by default. 

Admin/publisher credentials authentication and operation requires manual setup of a one time use X-XSRF-TOKEN for most requests (if a method returns "The provided antiforgery token failed a custom data check" this means you need to get a new xsrf token before calling it, if it doesn't - you can just call it without getting a new xsrf token ). The basic algorithm for this authentication should be the following:

1. Get Antiforgery token (api/xsrf/get)
2. Log in and receive secure cookies (api/account/login) You need to do this only once during a session.
3. Get Antiforgery token again (api/xsrf/get)
4. Call a method that requires xsrf token (like sending alert with publisher/alert/create)
5. Repeat 3-4 for other API calls you would need to make 

Please refer to PowerShell example script below, where function Get-NewXSRFHeader returns a fresh xsrf token that can be used in the header for the next request that need it.

Send an alert in PowerShell using Admin/publisher credentials

Below is a PowerShell script that sends a pop-up alert to a user named "John Doe". Please note that API calls in this example use the bare minimum of the required parameters that you can specify:

PowerShell

# Define your DeskAlerts API endpoint and credentials

$APIEndpoint = "https://yourdeskalertsserver.com/DeskAlerts/api/"
$UserName = "admin"
$SaltedPassword = "YourSaltedPassword"

# Define a session variable to store cookies in
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession

# Define a function that will request a new XSRF token and return a header data for the next request that needs it
Function Get-NewXSRFHeader {
    $GetXSRFURL = $APIEndpoint + "xsrf/get"
    Invoke-RestMethod -Uri $GetXSRFURL -Method Get -WebSession $Session | Out-Null # Suppress unnecessary output
    $data = @{
        'X-XSRF-TOKEN' = $Session.Cookies.GetCookies($GetXSRFURL)["XSRF-TOKEN"].Value
        "Content-Type" = "application/json"
    }
    return $data
}
# Login request data
$Body = @{
    role     = "1"
    username = "$UserName"
    password = "$SaltedPassword"
} | ConvertTo-Json

# Log in
$URL = $APIEndpoint + "account/login"
$response = Invoke-RestMethod -Uri $URL -Method Post -Body $Body -WebSession $Session -Headers (Get-NewXSRFHeader)

# "John Doe" user search data
$Body = @{
    name     = "John Doe"
    filterMode = "1"
} | ConvertTo-Json

# Serch for user "John Doe"
$URL =  $APIEndpoint + "organization/users"
$response = Invoke-RestMethod -Uri $URL -Method Post -Body $Body -WebSession $Session -Headers (Get-NewXSRFHeader)

# Get it's userid
$UserId = $response.data.userid
# Compose the alert data for "John Doe"
$Body = @{
    body     = "This alert was sent through DeskAlerts 11 REST API to a user John Doe"
    title = "DeskAlerts 11 REST API test"
    skinId = "1"
    recipients = @(
        @{
            id   = $UserId
            type = "User"
        }
    )
} | ConvertTo-Json

# Send the alert
$URL =  $APIEndpoint + "publisher/alert/create"
$response = Invoke-RestMethod -Uri $URL -Method Post -Body $Body -WebSession $Session -Headers (Get-NewXSRFHeader)

Send an alert in Postman using Admin/publisher credentials

We have created a small Postman collection to get you started with the basics, please download the Postman collection json file from the attachment at the end of this article.
Import it in postman from File > Import
This collection also uses the Admin/publisher authentication and variables for credentials and endpoint URL.
Open the collection variables tab and replace the placeholder values of variables username, salted-password and DeskAlertsURL with your actual values:

Once the variables have been set up, make calls in this order:

1. Get Antiforgery token
2. Log in
3. Get Antiforgery token
4. Send alert to user with id 5

Your user with id 5 should receive an alert from the server. Please feel free to change the parameters according to your actual user data.

What's next

If you have a specific DeskAlerts REST API automation idea in mind, try to perform the desired actions in browser with developer tools opened and observe which API methods get called in the Network tab. Once you know what methods you need, you can Inspect them in Swagger and see which parameters they take and return.

All requests require you to log in once to collect the security cookies.

Requests that have method "xsrf/get" called before them require a fresh XSRF token set in the header, you can call the Get-NewXSRFHeader function from example above directly in header parameter to set it up. Other request do not require such header, for example api/publisher/template method that returns text templates.