Adds or removes a user from a role. Membership is per individual user account -- there's no AD-group-based membership; every caller (Windows/domain, Azure AD, or an app account) resolves down to one AppUser row by username, and that row's role memberships are what's checked.

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 and the role's id (from List Roles; user ids come from the Security & Audit user-management endpoints).
  3. Add or remove the membership.

The calls

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

No request body for either -- both ids are in the route.

Permission needed: Security.Manage for both.

C# example

// 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 and the role's id.
var userId = 33;
var roleId = 9;

// Step 3: Add the membership.
var addResponse = await client.PostAsync($"/api/security/users/{userId}/roles/{roleId}", null);
addResponse.EnsureSuccessStatusCode();
Console.WriteLine("Added.");

// -- later --

// Step 3: Remove the membership.
var removeResponse = await client.DeleteAsync($"/api/security/users/{userId}/roles/{roleId}");
removeResponse.EnsureSuccessStatusCode();
Console.WriteLine("Removed.");

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 and the role's id.
$userId = 33
$roleId = 9

# Step 3: Add the membership. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/security/users/$userId/roles/$roleId" -Method Post -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Added."

# -- later --

# Step 3: Remove the membership.
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/security/users/$userId/roles/$roleId" -Method Delete -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Removed."

What you get back

204 No Content for both -- no body. Adding someone already in the role is a harmless no-op (still 204); removing is unconditional (no error if they weren't in it).

Codes this call can return

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

  • 204 -- added, or already a member (add); removed, or wasn't a member (remove).
  • 400 -- (add) Identity rejected the operation internally.
  • 403 -- you don't have Security.Manage.
  • 404 -- no user or no role exists with that id.

What gets audited

Add is recorded as AppUser / Assign Role, remove as AppUser / Unassign Role, both with the username and role name in the after-state. (The no-op "already a member" case on add doesn't write an audit row, since nothing actually changed.)

See also: List Roles, Check Effective Permissions, Get a User's Permission Report.