> For the complete documentation index, see [llms.txt](https://docs.truedat.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.truedat.io/v8.12/api-integrations/authentication-management/password.md).
# Password
## Update a user password
> Updates a password. The endpoint has two modes, selected by which fields are present in the request body:\
> \
> \*\*Administrator mode\*\* — \`user.id\` and \`user.new\_password\` are supplied.\
> \- Requires administrator privileges.\
> \- The caller must not target their own account: administrators change their own password through user mode.\
> \- The response is the updated user document.\
> \
> \*\*User mode\*\* — \`user.new\_password\` and \`user.old\_password\` are supplied.\
> \- Requires the current password in \`old\_password\`. If it does not match, the endpoint responds \`403\` with an empty body.\
> \- The response is the updated user document.\
> \
> In both modes the new password must be at least 6 characters long.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/password":{"put":{"description":"Updates a password. The endpoint has two modes, selected by which fields are present in the request body:\n\n**Administrator mode** — `user.id` and `user.new_password` are supplied.\n- Requires administrator privileges.\n- The caller must not target their own account: administrators change their own password through user mode.\n- The response is the updated user document.\n\n**User mode** — `user.new_password` and `user.old_password` are supplied.\n- Requires the current password in `old_password`. If it does not match, the endpoint responds `403` with an empty body.\n- The response is the updated user document.\n\nIn both modes the new password must be at least 6 characters long.\n","operationId":"TdAuthWeb.PasswordController.update","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordUpdateRequest"}}},"description":"Password update payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}},"description":"Password updated"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnauthorizedMessageResponse"}}},"description":"Unauthorized"},"403":{"description":"Forbidden. Emitted with an empty body when the caller is authenticated but supplies an incorrect current password in user mode."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHNotFoundResponse"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnprocessableEntityChangesetResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update a user password","tags":["Password"]}}},"components":{"schemas":{"PasswordUpdateRequest":{"additionalProperties":false,"description":"Password update payload. The endpoint has two modes, chosen by which fields are present:\n\n- **Administrator mode**: include `user.id` and `user.new_password`. The caller must hold administrator privileges and must not target their own account (administrators change their own password through user mode).\n- **User mode**: include `user.new_password` and `user.old_password`. The caller changes their own password and must supply the current one.\n","properties":{"user":{"additionalProperties":false,"properties":{"id":{"description":"Target user ID. Required in administrator mode.","nullable":true,"type":"integer"},"new_password":{"description":"New password. Must be at least 6 characters long.","format":"password","type":"string"},"old_password":{"description":"Current password. Required in user mode.","format":"password","nullable":true,"type":"string"}},"required":["new_password"],"type":"object"}},"required":["user"],"title":"PasswordUpdateRequest","type":"object"},"UserResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/User"}},"required":["data"],"title":"UserResponse","type":"object"},"User":{"additionalProperties":true,"description":"Full user representation returned by show and mutation endpoints.","properties":{"acls":{"description":"Domain roles held by the user, either directly or through their groups. Present only in the `show` response.","items":{"$ref":"#/components/schemas/UserAclEntry"},"type":"array"},"email":{"nullable":true,"type":"string"},"external_id":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"groups":{"description":"Names of the groups the user belongs to.","items":{"type":"string"},"type":"array"},"id":{"type":"integer"},"role":{"description":"High level role of the account (for example `admin`, `user`, `service`, `agent`).","nullable":true,"type":"string"},"user_name":{"nullable":true,"type":"string"}},"required":["id"],"title":"User","type":"object"},"UserAclEntry":{"additionalProperties":true,"description":"Domain role held by the user, either directly or through one of their groups.\n\nWhen the ACL is granted through a group, the `group` field is present. When granted directly to the user, `group` is absent.\n","properties":{"group":{"additionalProperties":true,"description":"Group through which the ACL is granted. Absent when the grant is direct.","nullable":true,"properties":{"alias":{"nullable":true,"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"resource":{"$ref":"#/components/schemas/AclResource"},"role":{"$ref":"#/components/schemas/AclRole"}},"required":["resource","role"],"title":"UserAclEntry","type":"object"},"AclResource":{"additionalProperties":true,"description":"Resource the ACL applies to.","properties":{"id":{"type":"integer"},"name":{"nullable":true,"type":"string"},"type":{"description":"Resource type, for example `domain` or `structure`.","type":"string"}},"required":["id","type"],"title":"AclResource","type":"object"},"AclRole":{"additionalProperties":true,"description":"Role granted by the ACL entry.","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"title":"AclRole","type":"object"},"AUTHUnauthorizedMessageResponse":{"additionalProperties":false,"description":"Response emitted by the authentication pipeline when credentials are missing or invalid.","properties":{"message":{"description":"Error type, e.g. \"unauthorized\".","type":"string"}},"required":["message"],"title":"AUTHUnauthorizedMessageResponse","type":"object"},"AUTHNotFoundResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHNotFoundResponse","type":"object"},"AUTHUnprocessableEntityChangesetResponse":{"additionalProperties":false,"description":"Response emitted for Ecto.Changeset validation failures. Keys under `errors` are the invalid field names and values are lists of messages.","properties":{"errors":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"}},"required":["errors"],"title":"AUTHUnprocessableEntityChangesetResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```
## Update a user password
> Updates a password. The endpoint has two modes, selected by which fields are present in the request body:\
> \
> \*\*Administrator mode\*\* — \`user.id\` and \`user.new\_password\` are supplied.\
> \- Requires administrator privileges.\
> \- The caller must not target their own account: administrators change their own password through user mode.\
> \- The response is the updated user document.\
> \
> \*\*User mode\*\* — \`user.new\_password\` and \`user.old\_password\` are supplied.\
> \- Requires the current password in \`old\_password\`. If it does not match, the endpoint responds \`403\` with an empty body.\
> \- The response is the updated user document.\
> \
> In both modes the new password must be at least 6 characters long.
```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/password":{"patch":{"description":"Updates a password. The endpoint has two modes, selected by which fields are present in the request body:\n\n**Administrator mode** — `user.id` and `user.new_password` are supplied.\n- Requires administrator privileges.\n- The caller must not target their own account: administrators change their own password through user mode.\n- The response is the updated user document.\n\n**User mode** — `user.new_password` and `user.old_password` are supplied.\n- Requires the current password in `old_password`. If it does not match, the endpoint responds `403` with an empty body.\n- The response is the updated user document.\n\nIn both modes the new password must be at least 6 characters long.\n","operationId":"TdAuthWeb.PasswordController.update (2)","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordUpdateRequest"}}},"description":"Password update payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}},"description":"Password updated"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnauthorizedMessageResponse"}}},"description":"Unauthorized"},"403":{"description":"Forbidden. Emitted with an empty body when the caller is authenticated but supplies an incorrect current password in user mode."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHNotFoundResponse"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnprocessableEntityChangesetResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update a user password","tags":["Password"]}}},"components":{"schemas":{"PasswordUpdateRequest":{"additionalProperties":false,"description":"Password update payload. The endpoint has two modes, chosen by which fields are present:\n\n- **Administrator mode**: include `user.id` and `user.new_password`. The caller must hold administrator privileges and must not target their own account (administrators change their own password through user mode).\n- **User mode**: include `user.new_password` and `user.old_password`. The caller changes their own password and must supply the current one.\n","properties":{"user":{"additionalProperties":false,"properties":{"id":{"description":"Target user ID. Required in administrator mode.","nullable":true,"type":"integer"},"new_password":{"description":"New password. Must be at least 6 characters long.","format":"password","type":"string"},"old_password":{"description":"Current password. Required in user mode.","format":"password","nullable":true,"type":"string"}},"required":["new_password"],"type":"object"}},"required":["user"],"title":"PasswordUpdateRequest","type":"object"},"UserResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/User"}},"required":["data"],"title":"UserResponse","type":"object"},"User":{"additionalProperties":true,"description":"Full user representation returned by show and mutation endpoints.","properties":{"acls":{"description":"Domain roles held by the user, either directly or through their groups. Present only in the `show` response.","items":{"$ref":"#/components/schemas/UserAclEntry"},"type":"array"},"email":{"nullable":true,"type":"string"},"external_id":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"groups":{"description":"Names of the groups the user belongs to.","items":{"type":"string"},"type":"array"},"id":{"type":"integer"},"role":{"description":"High level role of the account (for example `admin`, `user`, `service`, `agent`).","nullable":true,"type":"string"},"user_name":{"nullable":true,"type":"string"}},"required":["id"],"title":"User","type":"object"},"UserAclEntry":{"additionalProperties":true,"description":"Domain role held by the user, either directly or through one of their groups.\n\nWhen the ACL is granted through a group, the `group` field is present. When granted directly to the user, `group` is absent.\n","properties":{"group":{"additionalProperties":true,"description":"Group through which the ACL is granted. Absent when the grant is direct.","nullable":true,"properties":{"alias":{"nullable":true,"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"resource":{"$ref":"#/components/schemas/AclResource"},"role":{"$ref":"#/components/schemas/AclRole"}},"required":["resource","role"],"title":"UserAclEntry","type":"object"},"AclResource":{"additionalProperties":true,"description":"Resource the ACL applies to.","properties":{"id":{"type":"integer"},"name":{"nullable":true,"type":"string"},"type":{"description":"Resource type, for example `domain` or `structure`.","type":"string"}},"required":["id","type"],"title":"AclResource","type":"object"},"AclRole":{"additionalProperties":true,"description":"Role granted by the ACL entry.","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"title":"AclRole","type":"object"},"AUTHUnauthorizedMessageResponse":{"additionalProperties":false,"description":"Response emitted by the authentication pipeline when credentials are missing or invalid.","properties":{"message":{"description":"Error type, e.g. \"unauthorized\".","type":"string"}},"required":["message"],"title":"AUTHUnauthorizedMessageResponse","type":"object"},"AUTHNotFoundResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHNotFoundResponse","type":"object"},"AUTHUnprocessableEntityChangesetResponse":{"additionalProperties":false,"description":"Response emitted for Ecto.Changeset validation failures. Keys under `errors` are the invalid field names and values are lists of messages.","properties":{"errors":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"}},"required":["errors"],"title":"AUTHUnprocessableEntityChangesetResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```