# Subusers endpoints (Client API: VDS)

> 3 FeatherPanel Client API: VDS endpoints from user/vds/subusers.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Source: https://featherpanel.com/docs/api/reference/user/vds/subusers/

Defined in [`backend/app/routes/user/vds/subusers.php`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/vds/subusers.php). Authentication used here: **VDS access**. Read [Authentication](https://featherpanel.com/docs/api/authentication/) for how to send credentials and [Rate limits and errors](https://featherpanel.com/docs/api/rate-limits-and-errors/) for the response envelope.

Paths, methods, permissions and rate limits come from the route file. Summaries, parameters and response codes come from the OpenAPI annotations on the controllers; endpoints without annotations show only what the route file declares.

## Endpoints

### GET `/api/user/vm-instances/{id}/subusers`

- Auth: VDS access
- Default rate limit: 30 / minute
- Route name: `user-vm-instance-subusers-list`
- Controller: [`VmUserSubuserController::listSubusers`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Vds/VmUserSubuserController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/vds/subusers.php#L25)

**List subusers** List subusers for this VM instance. Only the VM owner can manage subusers.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes |  |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `subusers` | object\[\] |  |

```bash
curl -X GET "$PANEL_URL/api/user/vm-instances/$ID/subusers" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Subusers listed · `401` Unauthorized · `403` Only the VM owner can manage subusers · `404` VM instance not found

### POST `/api/user/vm-instances/{id}/subusers`

- Auth: VDS access
- Default rate limit: 10 / minute
- Route name: `user-vm-instance-subusers-create`
- Controller: [`VmUserSubuserController::createSubuser`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Vds/VmUserSubuserController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/vds/subusers.php#L39)

**Add subuser** Add a subuser to this VM instance with given permissions. Only the VM owner can add subusers.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes |  |

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes | Target user email |
| `permissions` | string\[\] | yes | e.g. power, console |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `subuser` | object |  |

```bash
curl -X POST "$PANEL_URL/api/user/vm-instances/$ID/subusers" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"","permissions":[]}'
```

Plugin events: [`featherpanel:vds:subuser:create`](https://featherpanel.com/docs/plugins/events/vds/#vds-subuser-created)

Responses: `201` Subuser added · `400` email and permissions required · `401` Unauthorized · `403` Only the VM owner can add subusers · `404` VM instance not found · `500` Create failed

### DELETE `/api/user/vm-instances/{id}/subusers/{subuserId}`

- Auth: VDS access
- Default rate limit: 10 / minute
- Route name: `user-vm-instance-subusers-delete`
- Controller: [`VmUserSubuserController::deleteSubuser`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Vds/VmUserSubuserController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/vds/subusers.php#L53)

**Remove subuser** Remove a subuser from this VM instance. Only the VM owner can remove subusers.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes |  |
| `subuserId` | path | integer | yes |  |

```bash
curl -X DELETE "$PANEL_URL/api/user/vm-instances/$ID/subusers/$SUBUSER_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:vds:subuser:delete`](https://featherpanel.com/docs/plugins/events/vds/#vds-subuser-deleted)

Responses: `200` Subuser removed · `401` Unauthorized · `403` Only the VM owner can remove subusers · `404` VM instance or subuser not found