# REST-API: Users

> Die 15 Operationen des Bereichs Users, mit Parametern, Bodys und Antworten.

Source: https://pithyx.org/de/docs/reference/api/users/
Markdown: https://pithyx.org/de/docs/reference/api/users.md

Erzeugt aus dem OpenAPI-Dokument des Daemons. Konventionen, Anmeldung, der CSRF-Header und der WebSocket stehen unter [API](https://pithyx.org/de/docs/developers/daemon/api/).

## GET /api/groups

Administrators only. Every group with its members, the built-in group users (every user) first.

**Antworten**

- 200: `application/json`: [GroupSummary](https://pithyx.org/de/docs/reference/api/schemas/#groupsummary)[]

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## POST /api/groups

Administrators only. Creates a group with a Linux group (a gid from 30000 to 39999 that is never given out again) and its members.

**Anfrage-Body**: `application/json`: [NewGroup](https://pithyx.org/de/docs/reference/api/schemas/#newgroup)

**Antworten**

- 201: `application/json`: [GroupSummary](https://pithyx.org/de/docs/reference/api/schemas/#groupsummary)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PATCH /api/groups/{groupId}

Administrators only. Renames a group, changes its description or sets its members; the gid stays. The built-in group cannot be changed.

**Parameter**

| Name      | Ort  | Typ             | Pflicht | Beschreibung |
| --------- | ---- | --------------- | ------- | ------------ |
| `groupId` | path | integer (int64) | ja      |              |

**Anfrage-Body**: `application/json`: [GroupUpdate](https://pithyx.org/de/docs/reference/api/schemas/#groupupdate)

**Antworten**

- 200: `application/json`: [GroupSummary](https://pithyx.org/de/docs/reference/api/schemas/#groupsummary)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## DELETE /api/groups/{groupId}

Administrators only. Deletes a group and its Linux group; files keep its gid, which is never given out again. The built-in group stays.

**Parameter**

| Name      | Ort  | Typ             | Pflicht | Beschreibung |
| --------- | ---- | --------------- | ------- | ------------ |
| `groupId` | path | integer (int64) | ja      |              |

**Antworten**

- 204

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## GET /api/homes

Administrators only. The home pool, every pool with whether it can take the homes, the default quota and every home with its user, space and quota, the homes of deleted users included.

**Antworten**

- 200: `application/json`: [HomeOverview](https://pithyx.org/de/docs/reference/api/schemas/#homeoverview)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## DELETE /api/homes/{shareId}

Administrators only. Deletes the home of a deleted user with every file and snapshot, after its folder name was typed (confirm).

**Parameter**

| Name      | Ort   | Typ             | Pflicht | Beschreibung |
| --------- | ----- | --------------- | ------- | ------------ |
| `shareId` | path  | integer (int64) | ja      |              |
| `confirm` | query | string          | nein    |              |

**Antworten**

- 204

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## POST /api/homes/{shareId}/release

Administrators only. Moves the files of a deleted user's home into a new folder of a shared folder as a job, then deletes the home with its recycle bin.

**Parameter**

| Name      | Ort  | Typ             | Pflicht | Beschreibung |
| --------- | ---- | --------------- | ------- | ------------ |
| `shareId` | path | integer (int64) | ja      |              |

**Anfrage-Body**: `application/json`: [HomeReleaseRequest](https://pithyx.org/de/docs/reference/api/schemas/#homereleaserequest)

**Antworten**

- 202: `application/json`: [Job](https://pithyx.org/de/docs/reference/api/schemas/#job)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## POST /api/homes/move

Administrators only. Moves every home to another pool as a job: each home is read-only while it is copied with its files, owners and ACLs, then it is used from the new pool and the old copy is destroyed. A home that fails stays where it was.

**Anfrage-Body**: `application/json`: [HomeMoveRequest](https://pithyx.org/de/docs/reference/api/schemas/#homemoverequest)

**Antworten**

- 202: `application/json`: [Job](https://pithyx.org/de/docs/reference/api/schemas/#job)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PUT /api/homes/settings

Administrators only. Sets the quota of every home without its own (at least 1 MiB, null for none).

**Anfrage-Body**: `application/json`: [HomeSettingsRequest](https://pithyx.org/de/docs/reference/api/schemas/#homesettingsrequest)

**Antworten**

- 200: `application/json`: [HomeOverview](https://pithyx.org/de/docs/reference/api/schemas/#homeoverview)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PUT /api/homes/users/{userId}/quota

Administrators only. Sets a user's own home quota: at least 1 MiB, 0 for none, null for the default.

**Parameter**

| Name     | Ort  | Typ             | Pflicht | Beschreibung |
| -------- | ---- | --------------- | ------- | ------------ |
| `userId` | path | integer (int64) | ja      |              |

**Anfrage-Body**: `application/json`: [HomeQuotaRequest](https://pithyx.org/de/docs/reference/api/schemas/#homequotarequest)

**Antworten**

- 200: `application/json`: [HomeOverview](https://pithyx.org/de/docs/reference/api/schemas/#homeoverview)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## GET /api/users

Administrators only. Every user with its Linux uid and home folder.

**Antworten**

- 200: `application/json`: [UserSummary](https://pithyx.org/de/docs/reference/api/schemas/#usersummary)[]

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## POST /api/users

Administrators only. Creates a user with a Linux and a Samba account with the password (a uid from 20000 to 29999 that is never given out again, the group users, no login shell) and its home on the home pool when there is one.

**Anfrage-Body**: `application/json`: [NewUser](https://pithyx.org/de/docs/reference/api/schemas/#newuser)

**Antworten**

- 201: `application/json`: [UserSummary](https://pithyx.org/de/docs/reference/api/schemas/#usersummary)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PATCH /api/users/{userId}

Administrators only. Changes the display name, the administrator right, the SMB and SFTP rights or whether the user is deactivated. Deactivating ends the user's sessions and expires the Linux account. The last active administrator keeps the right and stays active, and nobody deactivates themselves.

**Parameter**

| Name     | Ort  | Typ             | Pflicht | Beschreibung |
| -------- | ---- | --------------- | ------- | ------------ |
| `userId` | path | integer (int64) | ja      |              |

**Anfrage-Body**: `application/json`: [UserUpdate](https://pithyx.org/de/docs/reference/api/schemas/#userupdate)

**Antworten**

- 200: `application/json`: [UserSummary](https://pithyx.org/de/docs/reference/api/schemas/#usersummary)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## DELETE /api/users/{userId}

Administrators only. Deletes the user and its Linux account; its uid is never given out again and its other files stay. Its home stays as <name>.deleted-<uid> (home=keep, the default), is deleted with every file (home=delete with confirm set to the user name) or moves into a folder of the shared folder shareId as a job (home=move), which the answer returns. Nobody deletes themselves, and the last administrator stays.

**Parameter**

| Name      | Ort   | Typ             | Pflicht | Beschreibung |
| --------- | ----- | --------------- | ------- | ------------ |
| `userId`  | path  | integer (int64) | ja      |              |
| `home`    | query | string          | nein    |              |
| `shareId` | query | integer (int64) | nein    |              |
| `confirm` | query | string          | nein    |              |

**Antworten**

- 200: `application/json`: [UserDeletion](https://pithyx.org/de/docs/reference/api/schemas/#userdeletion)

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).

## PUT /api/users/{userId}/password

Administrators only. Sets a new password, for SMB and SFTP as well, and ends every session of the user.

**Parameter**

| Name     | Ort  | Typ             | Pflicht | Beschreibung |
| -------- | ---- | --------------- | ------- | ------------ |
| `userId` | path | integer (int64) | ja      |              |

**Anfrage-Body**: `application/json`: [PasswordReset](https://pithyx.org/de/docs/reference/api/schemas/#passwordreset)

**Antworten**

- 204

Jeder Fehler antwortet mit Problem Details (`application/problem+json`) und einem stabilen Code aus der [Fehlerreferenz](https://pithyx.org/de/docs/reference/errors/).