---
title: "Set or reset a user's password."
method: PUT
path: "/api/users/{username}/password"
tags: ["Users"]
---

# Set or reset a user's password.

`PUT /api/users/{username}/password`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/users/{username}/password`
- Auth: HTTP bearer

Sets another user's password without the current one. The user must change it at next sign-in, and their session keys are revoked. On the calling administrator's own user, this sets only the first password, with no change required, which is how the admin user gets one with the bootstrap API key; after that, use PUT /api/users/me/password. Requires an administrator as well as the scope. Recorded as a user_password_reset audit event when it replaces a password, or user_password_set when the user had none, naming the calling administrator and API key, never the password. Requires the `users:write` scope.

## Path parameters

- `username` string, required

## Headers

- `Authorization` string, required

## Request body

- SetPasswordRequest
  - `password` string: At least 16 characters and at most 72 bytes in UTF-8.

## Response `204`

The password was set.

## Other responses

- `400`: The password is missing, shorter than 16 characters, or longer than 72 bytes in UTF-8.
- `401`: The Authorization header is absent or the API key is not recognized.
- `403`: The key does not hold users:write, or the caller is not an administrator.
- `404`: There is no user with that username.
- `406`: No representation matches Accept.
- `409`: The user is the caller and already has a password, or the password was changed by a concurrent request.
- `413`: Content Too Large
- `415`: Unsupported Media Type
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-10** `c4f85daa9208`: 16 info
  - added the optional property `field` to the response with the `400` status
  - added the optional property `field` to the response with the `401` status
  - added the optional property `field` to the response with the `403` status
  - added the optional property `field` to the response with the `409` status
  - …12 more
- **2026-10-05** `4082c17721d8`: 5 breaking, 5 info
  - removed the media type `*/*` for the response with the status `401`
  - removed the media type `*/*` for the response with the status `413`
  - removed the media type `*/*` for the response with the status `415`
  - removed the media type `*/*` for the response with the status `500`
  - …6 more
- **2026-10-05** `4fa43795fff9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/philterd/apis/philter-api/changes/api/users/:username/password/put.md)

---

[API](https://skmtc.dev/philterd/apis/philter-api.md) - [All operations](https://skmtc.dev/philterd/apis/philter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/philterd/apis/philter-api/revisions/aa3d7ad1aab4?raw)