List Roles : MinionWare

Returns every role in the system, built-in and custom. IsBuiltIn roles can't be deleted (see Create / Delete a Role). BypassesSecurity marks a "Fleet Admin"-style role whose members skip normal permission checks entirely -- everything is allowed.

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.

Order of Operations

Authenticate to the API.
Request the list.

The call

GET /api/security/roles

No route parameters, no query parameters, no request body.

Permission needed: Security.Manage.

C# example

var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// Step 1: Authenticate to the API.
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");

// Step 2: Request the list.
var roles = await client.GetFromJsonAsync<RoleSummary[]>("/api/security/roles", jsonOptions);
foreach (var role in roles!)
{
    Console.WriteLine($"{role.RoleId}: {role.RoleName} (built-in = {role.IsBuiltIn}, bypasses security = {role.BypassesSecurity})");
}

record RoleSummary(int RoleId, string RoleName, bool IsBuiltIn, bool BypassesSecurity);

Not on a domain machine? Swap in the app-account login from Calling the API From Your Own Code.

PowerShell example

# Step 1: Authenticate to the API.
$headers = @{ "X-App-Name" = "MyIntegration" }

# Step 2: Request the list. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$roles = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/security/roles" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
$roles | ForEach-Object { "$($_.roleId): $($_.roleName) (built-in = $($_.isBuiltIn), bypasses security = $($_.bypassesSecurity))" }

What you get back

200 OK, an array:

[
    { "roleId": 1, "roleName": "Fleet Admin", "isBuiltIn": true, "bypassesSecurity": true },
    { "roleId": 4, "roleName": "Job Operators", "isBuiltIn": false, "bypassesSecurity": false }
]

Codes this call can return

See API Response Codes for what each one means in general. For this specific call:

200 -- the list, even if it's empty.
403 -- you don't have Security.Manage.

List Roles Print