Skip to content

Documentation / Tutorials

Enclave API Examples: Cleaning Up Inactive Systems

You can use our public APIs to automate any task achievable manually in the Enclave Portal.

As an example, we'll demonstrate how to automatically remove any systems that have not connected to the Enclave Platform for a period of time.

This lets you keep your set of enrolled systems tidy even when you aren't informed that a user has decommissioned an enrolled device.

Tip

You can invoke our APIs from your scripting language of choice. Check out our OpenAPI specification for individual API endpoint details.

We'll get to the working script in just a moment, but first, here are the list of steps we'll need to go through in order to use our API to clean-up old systems.

  1. Query our set of systems using the GET /org/$orgId/systems endpoint, making sure we include any disabled systems.
  2. Loop through each system, making sure we move to the next page of results when needed (using the links.next result property to get the URL for the next page of systems).
  3. For each entry in the system list, we get the lastSeen property. If there's no lastSeen value for a system (meaning it has never connected), we use the enrolledAt timestamp.
  4. If that lastSeen value is older than specified time period, we remove the system with the DELETE /org/$orgId/systems/<systemId> endpoint.

The Script

PowerShell provides the handy Invoke-RestMethod cmdlet, which makes it easy to call our APIs. Drop the content in the code block below into a .ps1 file and you can run it from the terminal (or Windows Task Scheduler).

To run this script you will need:

The script accepts the following arguments:

  • -orgId, the organisation to run queries against.
  • -apiKey, the Enclave API key. If you wish to avoid putting your API key in the command line, you can set the ENCLAVE_API_KEY environment variable instead.
  • -maxInactiveDays, the maximum number of inactive days to allow before a system is revoked (defaults to 90).
  • -test, which prints out the systems that the script would have revoked, but doesn't actually change anything.

If you configure this script to run automatically using your preferred mechanism, your systems will periodically clean themselves up!

Param(
    [Parameter(Mandatory=$true)]
    [string]$orgId,

    [Parameter()]
    [string]$apiKey = "",

    [Parameter()]
    [ValidateRange(1, [int]::MaxValue)]
    [int]$maxInactiveDays = 90,

    [Parameter()]
    [switch]$test = $false
)

$ErrorActionPreference = "Stop"

if ($apiKey -eq "")
{
    $apiKey = $env:ENCLAVE_API_KEY
}

if ($apiKey -eq "")
{
    Write-Error "No API key provided; either specify the 'apiKey' argument, or set the ENCLAVE_API_KEY environment variable."
    return;
}

# Attach our api key to each request.
$headers = @{Authorization = "Bearer $apiKey"}
$contentType = "application/json";

$uri = "https://api.enclave.io/org/$orgId/systems?per_page=50&include_disabled=true";
$currentDate = Get-Date

# Begin our loop through the pages of systems.
do {

    $systems = Invoke-RestMethod -ContentType $contentType -Uri $uri -Headers $headers

    foreach ($system in $systems.items) {    
        # Get the lastSeen field, or use the enrolement date if the system has never connected.
        $lastSeenText = if ($system.lastSeen) { $system.lastSeen } else { $system.enrolledAt }
        $lastSeen = Get-Date $lastSeenText;

        # How long between today and the lastSeen date?
        $age = $currentDate - $lastSeen;

        # Anything not seen in the configured number of days will be removed.
        if ($age.TotalDays -gt $maxInactiveDays)
        {
            "Removing $($system.hostname) ($($system.systemId)) after $([math]::Round($age.TotalDays)) days of inactivity"

            if (!$test)
            {
                # Invoke our API to delete the system from the organisation.
                Invoke-RestMethod -Uri "https://api.enclave.io/org/$orgId/systems/$($system.systemId)" -Headers $headers -Method Delete | Out-Null
            }
        }
    }

    # Get the url to the next page of systems.
    $uri = $systems.links.next;

} while($uri);