Sets (or replaces) a password for an account, or removes one entirely. This is what makes an account a password-based "app account" in practice -- see Manage App Accounts. You can change your own password without Security.Manage; changing someone else's needs it.

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 (from Manage App Accounts).
  3. Set or remove the password.

The calls

PUT    /api/security/users/{userId}/password
DELETE /api/security/users/{userId}/password

Permission needed: none extra to change your own password (self-service). Security.Manage to change or remove anyone else's, and always for removal even of your own (there's no self-service exemption on the DELETE).

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 = 41;

// Step 3: Set a password. CurrentPassword is only checked when you're changing your OWN password
// (and only if the fleet requires it) -- an admin resetting someone else's can leave it null.
var setRequest = new SetPasswordRequest(Password: "a-strong-new-password-1", CurrentPassword: null);
var response = await client.PutAsJsonAsync($"/api/security/users/{userId}/password", setRequest, jsonOptions);
response.EnsureSuccessStatusCode();
Console.WriteLine("Password set.");

// -- later, to remove it (requires Security.Manage even for your own account) --
var deleteResponse = await client.DeleteAsync($"/api/security/users/{userId}/password");
deleteResponse.EnsureSuccessStatusCode();
Console.WriteLine("Password removed.");

record SetPasswordRequest(string Password, string? CurrentPassword = null);

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 = 41

# Step 3: Set a password. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$setRequest = @{ Password = "a-strong-new-password-1"; CurrentPassword = $null } | ConvertTo-Json
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/security/users/$userId/password" `
    -Method Put -Body $setRequest -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Password set."

# -- later, to remove it --
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/security/users/$userId/password" -Method Delete -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Password removed."

What you get back

204 No Content for both -- no body.

Codes this call can return

See API Response Codes for what each one means in general. For these calls:

  • 204 -- set or removed.
  • 400 -- (PUT) Password is missing or shorter than 8 characters; or (self-service only, if the fleet requires it) CurrentPassword was missing or didn't match the account's actual current password.
  • 403 -- you're changing someone else's password without Security.Manage, or removing any password without it.
  • 404 -- no user exists with that id.

The 8-character minimum is the only rule this endpoint enforces directly -- it doesn't check the richer password-policy settings some fleets configure for the generated-password flow (Roles & Permissions area's fleet settings); those don't restrict what you can type in here.

What gets audited

Set is recorded as AppUser / Set Password, with a reason of "self-service" or "admin reset" -- the password itself is never audited, in any form. Remove is recorded as AppUser / Remove Password. Removing a password (or disabling the account -- see Enable / Disable a User) also immediately kills that user's active sessions.

See also: Manage App Accounts, Enable / Disable a User, Calling the API From Your Own Code.