# Permissions endpoints (Admin API)

> 5 FeatherPanel Admin API endpoints from admin/permissions.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Source: https://featherpanel.com/docs/api/reference/admin/permissions/

Defined in [`backend/app/routes/admin/permissions.php`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/permissions.php). Authentication used here: **Admin**. 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/admin/permissions`

- Auth: Admin
- Permission: `admin.roles.permissions.view`
- Route name: `admin-permissions`
- Controller: [`PermissionsController::index`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/PermissionsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/permissions.php#L26)

**Get all permissions** Retrieve a paginated list of all permissions with optional search functionality and role filtering.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Page number for pagination |
| `limit` | query | integer | no | Number of records per page |
| `search` | query | string | no | Search term to filter permissions by permission name |
| `role_id` | query | integer | no | Filter permissions by specific role ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `permissions` | Permission\[\] |  |
| `pagination` | PermissionPagination |  |
| `search` | object |  |

```bash
curl -X GET "$PANEL_URL/api/admin/permissions" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Permissions retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/permissions/{id}`

- Auth: Admin
- Permission: `admin.roles.permissions.view`
- Route name: `admin-permissions-show`
- Controller: [`PermissionsController::show`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/PermissionsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/permissions.php#L35)

**Get permission by ID** Retrieve a specific permission by its ID.

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

| Response `data` field | Type | Description |
| --- | --- | --- |
| `permission` | Permission |  |

```bash
curl -X GET "$PANEL_URL/api/admin/permissions/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Permission retrieved successfully · `400` Bad request - Invalid permission ID · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Permission not found

### PATCH `/api/admin/permissions/{id}`

- Auth: Admin
- Permission: `admin.roles.permissions.edit`
- Route name: `admin-permissions-update`
- Controller: [`PermissionsController::update`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/PermissionsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/permissions.php#L49)

**Update permission** Update an existing permission. Only provided fields will be updated. Validates role ID and permission name format.

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

Request body: [`PermissionUpdate`](https://featherpanel.com/docs/api/schemas/#schema-permissionupdate) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `role_id` | integer | no | Role ID |
| `permission` | string | no | Permission name |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `permission` | Permission |  |

```bash
curl -X PATCH "$PANEL_URL/api/admin/permissions/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"role_id":0,"permission":""}'
```

Plugin events: [`featherpanel:admin:permissions:permission:updated`](https://featherpanel.com/docs/plugins/events/permissions/#permission-updated)

Responses: `200` Permission updated successfully · `400` Bad request - Invalid JSON, no data provided, invalid data types, or validation errors · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Permission not found · `500` Internal server error - Failed to update permission

### DELETE `/api/admin/permissions/{id}`

- Auth: Admin
- Permission: `admin.roles.permissions.delete`
- Route name: `admin-permissions-delete`
- Controller: [`PermissionsController::delete`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/PermissionsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/permissions.php#L64)

**Delete permission** Permanently delete a permission from the database. This action cannot be undone.

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

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X DELETE "$PANEL_URL/api/admin/permissions/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:admin:permissions:permission:deleted`](https://featherpanel.com/docs/plugins/events/permissions/#permission-deleted)

Responses: `200` Permission deleted successfully · `400` Bad request - Invalid permission ID · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Permission not found · `500` Internal server error - Failed to delete permission

### PUT `/api/admin/permissions`

- Auth: Admin
- Permission: `admin.roles.permissions.create`
- Route name: `admin-permissions-create`
- Controller: [`PermissionsController::create`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/PermissionsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/permissions.php#L79)

**Create new permission** Create a new permission for a specific role. Validates role ID and permission name format.

Request body: [`PermissionCreate`](https://featherpanel.com/docs/api/schemas/#schema-permissioncreate) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `role_id` | integer | yes | Role ID |
| `permission` | string | yes | Permission name |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `permission` | Permission |  |

```bash
curl -X PUT "$PANEL_URL/api/admin/permissions" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"role_id":0,"permission":""}'
```

Plugin events: [`featherpanel:admin:permissions:permission:created`](https://featherpanel.com/docs/plugins/events/permissions/#permission-created)

Responses: `201` Permission created successfully · `400` Bad request - Invalid JSON, missing required fields, invalid data types, or validation errors · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `500` Internal server error - Failed to create permission