The Console and the Worker aren't special -- they talk to the same Api anyone else can call directly. If you want to script something against Minion Agent (a scheduled PowerShell job, a Splunk integration, your own homemade tool), you're calling the exact same endpoints they do.

Having trouble reaching the API, or logging in from another machine? See Network Access & Authentication Security -- by default the Api only answers localhost, and PowerShell needs an extra flag once it does answer elsewhere.

Signing in

Two ways in, same as signing into the Console itself:

  • Running on a domain machine as a recognized Windows account -- no separate sign-in step. Just send the request with your Windows credentials attached (see examples below) and it works.
  • Everything else (a script that isn't domain-joined, a service account you don't want to hand real Windows credentials to) -- sign in with an app account instead. App accounts are created under Settings -> Users; give it whatever Role it actually needs and nothing more. Signing in returns a token that's good for 12 hours; attach it to every request after that.

Every call has to say who it is

No matter how you're signed in, every single request must include an X-App-Name header naming your script or tool. Leave it out and the call is rejected outright -- there's no exception for "just this once" or "it's only a read." This isn't optional and it isn't something a setting can turn off.

This is what makes the Activity (Audit Log) actually useful when something unexpected changes: instead of just "jdoe dropped this job," you get "jdoe dropped this job, from Splunk" -- or from whatever you name your own script. Pick a name that means something to whoever reads that log later, not test or temp.

Examples

Replace the server address, credentials, and app name with your own. MyIntegration below is a stand-in -- use something that actually identifies your script.

C# -- already running as a trusted Windows account

using var handler = new HttpClientHandler { UseDefaultCredentials = true };
using var client = new HttpClient(handler) { BaseAddress = new Uri("http://your-minion-agent-server:5443") };
client.DefaultRequestHeaders.Add("X-App-Name", "MyIntegration");

var jobs = await client.GetFromJsonAsync<JobSummary[]>("/api/jobs");

C# -- signing in with an app account

// The Api sends JSON as camelCase ("sessionToken", not "SessionToken") --
// this option is what lets a plain PascalCase C# record still match it.
// Skip it and SessionToken silently comes back null instead of throwing.
var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);

using var client = new HttpClient { BaseAddress = new Uri("http://your-minion-agent-server:5443") };
client.DefaultRequestHeaders.Add("X-App-Name", "MyIntegration");

var loginResponse = await client.PostAsJsonAsync("/api/auth/login",
    new { UserName = "svc-myintegration", Password = "..." });
var login = await loginResponse.Content.ReadFromJsonAsync<LoginResult>(jsonOptions);

client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", login!.SessionToken);

var jobs = await client.GetFromJsonAsync<JobSummary[]>("/api/jobs", jsonOptions);

record LoginResult(string SessionToken, DateTime ExpiresAt, string UserName);

PowerShell -- already running as a trusted Windows account

$headers = @{ "X-App-Name" = "MyIntegration" }
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

-AllowUnencryptedAuthentication is required here: PowerShell 7+ refuses to send -UseDefaultCredentials (or an explicit -Credential) to anything other than localhost over plain http:// unless you say you mean it. It's PowerShell's own safeguard against sending a Windows credential handshake somewhere unencrypted -- nothing specific to this Api. It goes away once the Api is actually served over https:// (see Network Access & Authentication Security); leaving it in against an https:// URL is harmless.

PowerShell -- signing in with an app account

$loginBody = @{ UserName = "svc-myintegration"; Password = "..." } | ConvertTo-Json
$login = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/auth/login" `
    -Method Post -Body $loginBody -ContentType "application/json" `
    -Headers @{ "X-App-Name" = "MyIntegration" }

$headers = @{
    "X-App-Name"    = "MyIntegration"
    "Authorization" = "Bearer $($login.SessionToken)"
}
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs" -Headers $headers

See also: Activity (Audit Log), Roles, Permissions, and Identity.