Call a third-party API

Build a workflow action that calls a vendor's REST API with a stored API key and returns a short summary, so the SuperIT agent can look things up in that system when an engineer asks in chat. This is the pattern behind most of the integration guides in this section, for MSPs and IT teams using any tool that has an API.

Why use an action instead of asking SuperIT

SuperIT has no access to your other tools. It can't store their API keys and can't call arbitrary web APIs, only search the public web. An action holds the credential encrypted, calls the vendor's API in the cloud sandbox, and returns a short summary. That makes it a new tool SuperIT picks by name and description when an engineer asks in chat.

For anything SuperIT already knows, such as your tickets, your devices' readings or your Microsoft 365 directory, just ask SuperIT in chat.

When to use it

Once published, the action is a custom tool for the SuperIT agent. Engineers ask in plain language and SuperIT picks the action from its name and description:

• "What does our monitoring tool say about SRV-FS01?"
• "Look up this customer's contract in the billing system."
• "Is there an open alert for this device in the vendor console?"

Write the action's Description the way engineers ask. SuperIT reads it to decide when the action fits.

What the action does

1. Reads the search value from the action's input.
2. Reads the API key from the linked credential through an environment variable.
3. Sends one GET request to the vendor's API over HTTPS.
4. Prints a few readable lines and returns a small structured result, with only the fields it needs, that SuperIT summarises in chat.

What it doesn't do:

• It doesn't change anything in the vendor's system. Keep read and write in separate actions, so the write can have its own approval.
• It can't reach systems on a private network. The cloud sandbox reaches the public internet only, from fixed SuperIT IP addresses. For on-premises systems, see Query an on-premises system from a device.
• It can't install modules. The PowerShell sandbox has no Microsoft.Graph SDK or other add-on modules (apart from ExchangeOnlineManagement), so call APIs with Invoke-RestMethod.

Before you begin

• A credential. Under Workflows → Credentials, select New, give it a Name (this guide uses Vendor API) and pick the Auth scheme your vendor uses:

  • Other (Bearer token) sends Authorization: Bearer <key>. The script reads it as CREDENTIAL_VENDOR_API_AUTHORIZATION.
  • Other (custom header) sends a header you name, for example x-api-key, read as CREDENTIAL_VENDOR_API_X_API_KEY.
  • Other (Basic auth) sends Authorization: Basic ….

  The credential's Script environment variables panel shows the exact names. See Credentials. - A read-only API key if the vendor offers one. The action only needs to read. - An authorization policy, or none. With no policy, only engineers and admins can run the action, without approval. See Approvals. - Your role. Creating an action in chat needs the Admin role. Engineers can build it by hand under Workflows → Actions. - Allow-listing. If the vendor restricts API access by IP address, add SuperIT's fixed outbound IP addresses. See Network for how to get them.

Build it with SuperIT

Paste this into a chat with SuperIT and change the details for your vendor:

Create an action called "Look up device in Vendor Console".
Purpose: find a device in our vendor console by name and summarise its status, last check-in and open alerts.
Runtime: PowerShell in the cloud sandbox, using Invoke-RestMethod.
Input: search (string, required) - device name or serial number.
Credential: our "Vendor API" credential (Bearer token). API docs: <link to the vendor's API docs>.
It only reads. Return at most 10 matches with name, status and last seen.
No authorization policy: engineers and admins only, no approval.

SuperIT asks for anything missing, checks the credential's environment variable names, drafts the script, validates it and creates the action as a draft. You review the script, test it and publish it under Workflows → Actions.

Or build it yourself

Under Workflows → Actions, select Add action, then Create from scratch. On Credentials, link Vendor API. On Inputs, add:

On Script, set Runtime to PowerShell:

# Goal: search the vendor's API for a device by name or serial (read-only) and return up to 10 matches.
$baseUrl = "https://api.vendor.example/v1"   # your vendor's API base URL
$auth = $env:CREDENTIAL_VENDOR_API_AUTHORIZATION

function Invoke-VendorDeviceLookup {
    param([string]$Search)

    $query = $Search.Trim()
    Assert-Inputs -Query $query
    $devices = @(Get-VendorDevice -Query $query | ForEach-Object { ConvertTo-DeviceSummary -Device $_ })
    Write-DeviceSummary -Query $query -Devices $devices
    # $script: so the runner can still read $result after this function returns.
    $script:result = @{ query = $query; count = $devices.Count; devices = $devices }
}

function Assert-Inputs {
    param([string]$Query)
    if (-not $Query) { throw "Input 'search' is required." }
    if (-not $auth) { throw "The 'Vendor API' credential is not linked to this action." }
}

function Get-VendorDevice {
    param([string]$Query)
    $uri = "$baseUrl/devices?search=$([uri]::EscapeDataString($Query))"
    try {
        $data = Invoke-RestMethod -Uri $uri -Headers @{ Authorization = $auth; Accept = "application/json" } -TimeoutSec 30
    } catch {
        throw "Failed to search the vendor API for '$Query': $($_.Exception.Message)"
    }
    return @($data.items | Select-Object -First 10)
}

function ConvertTo-DeviceSummary {
    param($Device)
    # Copy only the fields SuperIT needs, so nothing else the vendor returns reaches the output or $result.
    [ordered]@{ name = "$($Device.name)"; status = "$($Device.status)"; last_seen = "$($Device.last_seen)" }
}

function Write-DeviceSummary {
    param([string]$Query, [object[]]$Devices)
    Write-Output "=== VENDOR DEVICE LOOKUP ==="
    Write-Output "Query   : $Query"
    Write-Output "Matches : $($Devices.Count)"
    foreach ($d in $Devices) {
        Write-Output "- $($d.name) | status: $($d.status) | last seen: $($d.last_seen)"
    }
}

Invoke-VendorDeviceLookup -Search $ctx.inputs.search

How SuperIT hands values to scripts (full details in the Sandbox and runtime reference):

• Inputs: $ctx.inputs.name. Every value is a string (booleans arrive as "true" or "false"), and a blank optional input is missing.
• Credentials: environment variables only. Never paste a key into the script.
• Shape: the script follows the structure SuperIT itself writes. A main function at the top reads as the plan, each step below it is a small function with one job, and the last line calls the main function once everything is defined.
• Output: Write-Output lines go to Stdout. Whatever you assign to $result appears under Result. Inside a function, assign it as $script:result; a plain $result = there is local to the function and SuperIT never sees it. Each stream keeps about 256 KB. Return only the fields SuperIT needs, as ConvertTo-DeviceSummary does, not the whole API response, which can carry fields you didn't expect.
• Failure: SuperIT sets $ErrorActionPreference = "Stop", so any error or throw marks the run failed and shows the message under Stderr.

Test it

1. Save the draft, then select Test (or Save and test).
2. Read the dialog. Test is not a dry run: it skips authorization and approvals, uses the real credential and network access, and can change real systems. Test runs aren't billed.
3. Tick the confirmation box, enter a search value you know exists, and select Start test run.
4. Check Stdout and Result. Then test with a value that doesn't exist and confirm the output says so clearly.
5. When it works, select Publish.

Use it

• In chat: an engineer asks "Look up SRV-FS01 in the vendor console". SuperIT runs the published action through its action-run tool and summarises the output. Engineers and admins see the full output. An end user who runs an action sees a redacted view of its output, so lookup actions like this one suit engineers best. See End users and approvals.
• From the UI: open the action and select Run.
• From a ticket: SuperIT can recommend the action after investigating a ticket. With Run automatically on, the recommendation runs it once every input is known. The investigation can only recommend actions: it doesn't run them itself or read their output, so a lookup's answer is in the run's output, not in the investigation's findings.
• For managed teams: publish it to managed teams with Publish to teams. Each team gets a read-only copy and a blank Vendor API credential that its admin fills in with that team's own key.

Variations

• OAuth client-credentials APIs. SuperIT's OAuth credentials work with Microsoft only. For other vendors, store the client ID and secret in a Custom HTTP headers credential and request the token in the script. See Look up device warranty.
• Paginated APIs. Loop over pages until there is no next link, but stop at a sensible maximum.
• Several systems in one answer. Call two APIs and return one combined summary, for example the device in your RMM and the matching asset in your documentation platform.

Related

• Credentials
• Approvals
• Look up a device in your documentation platform
• Query an on-premises system from a device