Grants, denies, or clears a permission for a role, fleet-wide ("Everywhere" scope -- applies to every job, folder, target server, and step). For a permission that should only apply to one specific job/folder/server/step, use Grant a Scoped Permission instead.

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 role's id (from List Roles) and the permission key (from List All Permission Keys).
  3. Set the fleet-wide grant.

The call

PUT /api/security/roles/{roleId}/permissions/{permissionKey}

Also see GET /api/security/role-permissions below, to read back every role's current fleet-wide grants in one call.

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: You already have the role's id and permission key.
var roleId = 9;
var permissionKey = "Job.Run";

// Step 3: Set the fleet-wide grant. IsDeny: false = allow, true = explicit deny, null = clear (remove the grant entirely).
var response = await client.PutAsJsonAsync($"/api/security/roles/{roleId}/permissions/{permissionKey}", new SetPermissionRequest(IsDeny: false), jsonOptions);
response.EnsureSuccessStatusCode();
Console.WriteLine("Updated.");

// Read back every role's fleet-wide grants.
var grants = await client.GetFromJsonAsync<RolePermissionGrant[]>("/api/security/role-permissions", jsonOptions);
foreach (var grant in grants!)
{
    Console.WriteLine($"Role {grant.RoleId}: {grant.PermissionKey}, deny = {grant.IsDeny}");
}

record SetPermissionRequest(bool? IsDeny);
record RolePermissionGrant(int RoleId, string PermissionKey, bool IsDeny);

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 role's id and permission key.
$roleId = 9
$permissionKey = "Job.Run"

# Step 3: Set the fleet-wide grant. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$body = @{ IsDeny = $false } | ConvertTo-Json
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/security/roles/$roleId/permissions/$permissionKey" `
    -Method Put -Body $body -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Updated."

# Read back every role's fleet-wide grants.
$grants = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/security/role-permissions" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
$grants | ForEach-Object { "Role $($_.roleId): $($_.permissionKey), deny = $($_.isDeny)" }

What you get back

PUT -- 204 No Content -- no body.

GET /api/security/role-permissions -- 200 OK, an array:

[
    { "roleId": 9, "permissionKey": "Job.Run", "isDeny": false }
]

IsDeny values

  • false -- explicit allow.
  • true -- explicit deny (wins over an allow from any other role the same user is in).
  • null (on PUT only) -- removes the fleet-wide grant row entirely, same as never having set it.

Codes this call can return

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

  • 204 -- updated (PUT).
  • 200 -- the list (GET).
  • 403 -- you don't have Security.Manage.
  • 404 -- (PUT) no role exists with that id.

What gets audited

Recorded as AppRole / Set Role Permission, with the role's name, the permission key, and the new IsDeny value in the after-state. The GET isn't audited (it's a read).

See also: List Roles, List All Permission Keys, Grant a Scoped Permission.