Walks one user's entire permission footprint -- every job, folder, target server, and step they have any grant on, through any role -- in a single call. This is the same report behind the Console's Permissions-by-User screen, exposed here so you can pull it into your own tooling. For a quick yes/no on one specific permission, use Check Effective Permissions instead; this call is the fuller "everything about this user" picture.

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

  1. Authenticate to the API.
  2. Get the user's id.
  3. Request their permission report.

The call

GET /api/security/users/{userId}/permission-report

Permission needed: Security.Manage -- always, even for your own account (unlike Check Effective Permissions, there's no self-service exemption here, since this walks an arbitrary user's whole footprint rather than answering one targeted question).

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: You already have the user's id.
var userId = 33;

// Step 3: Request their permission report.
var report = await client.GetAsync($"/api/security/users/{userId}/permission-report");
report.EnsureSuccessStatusCode();
var json = await report.Content.ReadAsStringAsync();
Console.WriteLine(json);

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: You already have the user's id.
$userId = 33

# Step 3: Request their permission report. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$reportJson = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/security/users/$userId/permission-report" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
$reportJson | ConvertTo-Json -Depth 10

What you get back

200 OK -- a report grouping every grant this user holds by role and by scope (job/folder/server/step), similar in shape to the entries Check Effective Permissions returns, but covering every permission and every scope the user touches rather than one you specify. Treat the exact shape as informational; pull it as JSON and inspect it rather than binding to a fixed schema, since this report is intentionally the "everything" dump.

Codes this call can return

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

  • 200 -- the report.
  • 403 -- you don't have Security.Manage.

Not audited -- it's a read-only report.

See also: Check Effective Permissions, Manage Role Membership.