Check Effective Permissions : MinionWare

Tells you whether a given permission actually applies for a user, at an optional scope -- combining every role they're in, every fleet-wide and scoped grant, and any explicit deny, into one yes/no answer per permission key, plus a trail of exactly which grants contributed. Useful for "can this user do X" checks in your own tooling without re-implementing the resolution logic yourself.

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.
(Optional) Decide whose permissions to check, and at what scope.
Request the effective permissions.

The call

GET /api/security/effective-permissions

Query params, all optional: userName (defaults to you, the caller), jobStepId, jobId, folderId, serverId (check against a specific scope instead of fleet-wide).

Permission needed: none, to check your own permissions. Security.Manage if userName names someone else.

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 & 3: Check another user's effective permissions on a specific job (requires Security.Manage).
var jobId = 214;
var effective = await client.GetFromJsonAsync<EffectivePermission[]>(
    $"/api/security/effective-permissions?userName=jsmith&jobId={jobId}", jsonOptions);
foreach (var perm in effective!)
{
    Console.WriteLine($"{perm.PermissionKey}: effective = {perm.Effective}");
    foreach (var trace in perm.ContributingGrants)
        Console.WriteLine($"    via role '{trace.RoleName}' at {trace.ScopeLevel}, deny = {trace.IsDeny}");
}

record PermissionGrantTrace(string RoleName, string ScopeLevel, bool IsDeny);
record EffectivePermission(string PermissionKey, string DisplayName, bool Effective, PermissionGrantTrace[] ContributingGrants);

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 & 3: Check another user's effective permissions on a specific job (requires Security.Manage). (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$jobId = 214
$effective = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/security/effective-permissions?userName=jsmith&jobId=$jobId" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
$effective | ForEach-Object {
    "$($_.permissionKey): effective = $($_.effective)"
    $_.contributingGrants | ForEach-Object { "    via role '$($_.roleName)' at $($_.scopeLevel), deny = $($_.isDeny)" }
}

What you get back

200 OK, an array covering every permission key in the catalog:

[
    {
        "permissionKey": "Job.Run",
        "displayName": "Run Jobs",
        "effective": true,
        "contributingGrants": [
            { "roleName": "Job Operators", "scopeLevel": "Job", "isDeny": false }
        ]
    }
]

Codes this call can return

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

200 -- the result.
400 -- no userName given and the caller's own identity couldn't be resolved (e.g. a bad/expired Azure AD token).
403 -- userName names someone else and you don't have Security.Manage.

Not audited -- it's a read-only check, not a change.

Check Effective Permissions Print