Creates a new custom role, or deletes one. There's no rename -- pick the name carefully at creation, or delete and recreate. A role starts with no permissions at all; grant it some with Set a Role's Fleet-Wide Permissions or Grant a Scoped Permission.

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

To create:

  1. Authenticate to the API.
  2. Send the new role's name.

To delete:

  1. Authenticate to the API.
  2. Get the role's id (from List Roles).
  3. Delete it.

The calls

POST   /api/security/roles
DELETE /api/security/roles/{roleId}

Permission needed: Security.Manage for both.

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: Send the new role's name.
var response = await client.PostAsJsonAsync("/api/security/roles", new CreateRoleRequest("Report Viewers"), jsonOptions);
response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<RoleSummary>(jsonOptions);
Console.WriteLine($"Created role id: {created!.RoleId}");

// -- later --

// Step 2: You already have the role's id (from List Roles).
var roleId = created.RoleId;

// Step 3: Delete it.
var deleteResponse = await client.DeleteAsync($"/api/security/roles/{roleId}");
deleteResponse.EnsureSuccessStatusCode();
Console.WriteLine("Deleted.");

record CreateRoleRequest(string RoleName);
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: Send the new role's name. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$body = @{ RoleName = "Report Viewers" } | ConvertTo-Json
$created = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/security/roles" `
    -Method Post -Body $body -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Created role id: $($created.roleId)"

# -- later --

# Step 2: You already have the role's id (from List Roles).
$roleId = $created.roleId

# Step 3: Delete it.
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/security/roles/$roleId" `
    -Method Delete -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Deleted."

What you get back

POST -- 201 Created:

{ "roleId": 9, "roleName": "Report Viewers", "isBuiltIn": false, "bypassesSecurity": false }

DELETE -- 204 No Content -- no body.

Codes this call can return

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

  • 201 -- role created.
  • 204 -- role deleted.
  • 400 -- (create) the name is blank, or Identity rejected it (e.g. a duplicate it caught internally).
  • 403 -- you don't have Security.Manage.
  • 404 -- (delete) no role exists with that id.
  • 409 -- (create) a role with that name already exists; (delete) the role is built-in and can't be deleted.

What gets audited

Create is recorded as AppRole / Create Role; delete as AppRole / Delete Role, both with the role's name in the before/after-state.

See also: List Roles, Set a Role's Fleet-Wide Permissions, Manage Role Membership.