Users endpoints (Admin API)

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

Last synced from FeatherPanel 15b94e9 on 23 Oct 2026.

On this page

Defined in backend/app/routes/admin/users.php. Authentication used here: Admin. Read Authentication for how to send credentials and 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/users`

Auth: AdminPermission: admin.users.listRoute name: admin-usersController: UsersController::indexroute source

Get all users Retrieve a paginated list of all users with role information, search functionality, and comprehensive user data.

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 users by username, email, or name
`role`	query	integer	no	Filter users by role ID
`banned`	query	string	no	Filter users by banned status (true/false)
`user_id`	query	integer	no	Filter users by numeric ID
`uuid`	query	string (uuid)	no	Filter users by UUID
`external_id`	query	string	no	Filter users by external ID
`ip`	query	string	no	Filter users by first or last IP address (partial match)
`email_verified`	query	string	no	Filter users by email verification status (true/false)
`sort_by`	query	string	no	Field to sort users by (id, username, email, last_seen, created_at)
`sort_order`	query	string	no	Sort order (ASC or DESC)

Response `data` field	Type	Description
`users`	User[]
`pagination`	UserPagination
`search`	object

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

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

GET`/api/admin/users/{uuid}`

Auth: AdminPermission: admin.users.listRoute name: admin-users-showController: UsersController::showroute source

Get user by UUID Retrieve a specific user by UUID with comprehensive information including role details, activity history, and mail history.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID

Response `data` field	Type	Description
`user`	User
`roles`	object	Available roles mapping

curl -X GET "$PANEL_URL/api/admin/users/$UUID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 User retrieved successfully · 400 Bad request - Invalid UUID format · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found

GET`/api/admin/users/external/{externalId}`

Auth: AdminPermission: admin.users.listRoute name: admin-users-show-by-external-idController: UsersController::showByExternalIdroute source

Get user by external ID Retrieve a specific user by its external ID with comprehensive information including role details, activity history, and mail history.

Parameter	In	Type	Required	Description
`externalId`	path	string	yes	User external ID

Response `data` field	Type	Description
`user`	User
`roles`	object	Available roles mapping

curl -X GET "$PANEL_URL/api/admin/users/external/$EXTERNAL_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

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

PATCH`/api/admin/users/{uuid}`

Auth: AdminPermission: admin.users.editRoute name: admin-users-updateController: UsersController::updateroute source

Update user Update an existing user with comprehensive validation, password hashing, email notifications for ban/unban, and activity logging.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID

Request body: UserUpdate (application/json)

Body field	Type	Required	Description
`username`	string	no	Username
`first_name`	string	no	First name
`last_name`	string	no	Last name
`email`	string (email)	no	Email address
`password`	string	no	Password
`avatar`	string (uri)	no	Avatar URL
`role_id`	integer	no	Role ID
`banned`	boolean	no	Banned status

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

curl -X PATCH "$PANEL_URL/api/admin/users/$UUID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"username":"","first_name":"","last_name":"","email":"","password":"","avatar":"","role_id":0,"banned":false}'

Plugin events: featherpanel:user:updated

Responses: 200 User updated successfully · 400 Bad request - No data provided, invalid data types, invalid data length, or invalid email format · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found · 409 Conflict - Email or username already exists · 500 Internal server error - Failed to update user

DELETE`/api/admin/users/{uuid}`

Auth: AdminPermission: admin.users.deleteRoute name: admin-users-deleteController: UsersController::deleteroute source

Delete user Permanently delete a user with activity logging, event emission, and account deletion email notification.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID

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

curl -X DELETE "$PANEL_URL/api/admin/users/$UUID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 User deleted successfully · 400 Bad request - Invalid UUID format · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found · 409 Conflict - User has active servers or VDS instances and cannot be deleted · 500 Internal server error - Failed to delete user or send account deleted email

PUT`/api/admin/users`

Auth: AdminPermission: admin.users.createRoute name: admin-users-createController: UsersController::createroute source

Create new user Create a new user with comprehensive validation, password hashing, UUID generation, welcome email, and activity logging.

Request body: UserCreate (application/json)

Body field	Type	Required	Description
`username`	string	yes	Username
`first_name`	string	yes	First name
`last_name`	string	yes	Last name
`email`	string (email)	yes	Email address
`password`	string	yes	Password
`avatar`	string (uri)	no	Avatar URL
`role_id`	integer	no	Role ID (defaults to 1)

Response `data` field	Type	Description
`user_id`	integer	Created user ID

curl -X PUT "$PANEL_URL/api/admin/users" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"username":"","first_name":"","last_name":"","email":"","password":"","avatar":"","role_id":0}'

Plugin events: featherpanel:user:created

Responses: 201 User created successfully · 400 Bad request - Missing required fields, invalid data types, invalid data length, or invalid email format · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 409 Conflict - Email or username already exists · 500 Internal server error - Failed to create user

GET`/api/admin/users/{uuid}/servers`

Auth: AdminPermission: admin.users.listRoute name: admin-users-owned-serversController: UsersController::ownedServersroute source

Get user owned servers Retrieve all servers owned by a specific user with basic server information.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID

Response `data` field	Type	Description
`servers`	AdminUserServer[]

curl -X GET "$PANEL_URL/api/admin/users/$UUID/servers" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Owned servers retrieved successfully · 400 Bad request - Invalid UUID format · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found

GET`/api/admin/users/{uuid}/vm-instances`

Auth: AdminPermission: admin.users.listRoute name: admin-users-owned-vm-instancesController: UsersController::ownedVmInstancesroute source

Get user owned VM instances Retrieve VM instances owned by a specific user with pagination and search.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID
`page`	query	integer	no
`limit`	query	integer	no
`search`	query	string	no

curl -X GET "$PANEL_URL/api/admin/users/$UUID/vm-instances" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Owned VM instances retrieved successfully · 400 Bad request - Invalid UUID format · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found

GET`/api/admin/users/{uuid}/potential-alts`

Auth: AdminPermission: admin.users.listRoute name: admin-users-potential-altsController: UsersController::potentialAltsroute source

Find potential alt accounts by IP Find other users who may be alternate accounts by comparing IP addresses from activity logs and first/last IP fields.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID

Response `data` field	Type	Description
`potential_alts`	object[]
`source_ips`	string[]
`total`	integer

curl -X GET "$PANEL_URL/api/admin/users/$UUID/potential-alts" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Potential alt accounts retrieved successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found

DELETE`/api/admin/users/{uuid}/devices`

Auth: AdminPermission: admin.users.editRoute name: admin-users-clear-devicesController: UsersController::clearUserDevicesroute source

Clear device fingerprints for a user Remove all browser/device sync records associated with a user. Useful when clearing false positives or after support review.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID

curl -X DELETE "$PANEL_URL/api/admin/users/$UUID/devices" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Device records cleared successfully · 404 User not found

POST`/api/admin/users/alt-detection/reset`

Auth: AdminPermission: admin.users.editRoute name: admin-users-alt-detection-resetController: UsersController::resetAltDetectionroute source

Reset alt detection for all users Clears every device fingerprint and ignores all IP evidence recorded before now when matching alts. Activity logs are kept.

curl -X POST "$PANEL_URL/api/admin/users/alt-detection/reset" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Alt detection reset

DELETE`/api/admin/devices`

Auth: AdminPermission: admin.users.editRoute name: admin-devices-clear-allController: UsersController::clearAllDevicesroute source

Clear all device fingerprints globally Remove every browser/device sync record in the panel. Use after policy changes or to reset alt detection data.

curl -X DELETE "$PANEL_URL/api/admin/devices" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 All device records cleared successfully

GET`/api/admin/users/serverRequest/{id}`

Auth: AdminPermission: admin.users.listRoute name: admin-users-server-requestController: UsersController::serverRequestroute source

Get server request by id (INTERNAL USE ONLY) - DO NOT USE THIS ENDPOINT IN YOUR CODE! Retrieve a server request by its ID (INTERNAL USE ONLY) - DO NOT USE THIS ENDPOINT IN YOUR CODE!

Parameter	In	Type	Required	Description
`id`	path	integer	yes	User ID

Response `data` field	Type	Description
`user`	User

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

Responses: 200 User retrieved successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found

POST`/api/admin/users/{uuid}/sso-token`

Auth: AdminPermission: admin.users.editRoute name: admin-users-sso-tokenController: UsersController::createSsoTokenroute source

Create SSO login token for user Generate a short-lived single sign-on (SSO) token that can be used to log the user in via the public login endpoint.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID

Body field	Type	Required	Description
`expires_in`	integer	no	Token lifetime in minutes (overrides the admin default when provided)

Response `data` field	Type	Description
`token`	string	SSO login token
`expires_in`	integer	Token expiration time in minutes

curl -X POST "$PANEL_URL/api/admin/users/$UUID/sso-token" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"expires_in":0}'

Responses: 200 SSO token created successfully · 400 Bad request - Invalid expires_in value · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found

POST`/api/admin/users/{uuid}/send-email`

Auth: AdminPermission: admin.users.editRoute name: admin-users-send-emailController: UsersController::sendEmailroute source

Send email to user Queue a direct email to a specific user with subject and HTML body content.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID

Body field	Type	Required	Description
`subject`	string	yes
`body`	string	yes	HTML content is supported

curl -X POST "$PANEL_URL/api/admin/users/$UUID/send-email" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"subject":"","body":""}'

Responses: 200 Email queued successfully · 400 Bad request · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found · 500 Internal server error - Failed to queue email

POST`/api/admin/users/{uuid}/mails/{id}/resend`

Auth: AdminPermission: admin.users.editRoute name: admin-users-resend-mailController: UsersController::resendMailroute source

Resend a failed user email Re-queue a failed system email for delivery to the specified user.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID
`id`	path	integer	yes	Mail list entry ID

curl -X POST "$PANEL_URL/api/admin/users/$UUID/mails/$ID/resend" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Email queued for resend · 400 Bad request - Mail cannot be resent or SMTP disabled · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User or mail not found · 500 Internal server error - Failed to resend mail

POST`/api/admin/users/{uuid}/verify-email`

Auth: AdminPermission: admin.users.editRoute name: admin-users-verify-emailController: UsersController::forceVerifyEmailroute source

Force verify user email Mark a user email address as verified by clearing their pending email verification token.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID

curl -X POST "$PANEL_URL/api/admin/users/$UUID/verify-email" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:user:updated

Responses: 200 User email verified successfully · 400 Bad request - User is already verified or demo mode restriction · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found · 500 Internal server error - Failed to verify email

POST`/api/admin/users/{uuid}/ban`

Auth: AdminPermission: admin.users.editRoute name: admin-users-banController: UsersController::banroute source

Ban a user Ban a user account. The user will be immediately blocked from all authenticated endpoints and receive a suspension email notification.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID

curl -X POST "$PANEL_URL/api/admin/users/$UUID/ban" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:user:updated

Responses: 200 User banned successfully · 400 Bad request - User is already banned or demo mode restriction · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found · 500 Internal server error - Failed to ban user

POST`/api/admin/users/{uuid}/unban`

Auth: AdminPermission: admin.users.editRoute name: admin-users-unbanController: UsersController::unbanroute source

Unban a user Unban a user account. The user will regain access to all authenticated endpoints and receive an unsuspension email notification.

Parameter	In	Type	Required	Description
`uuid`	path	string (uuid)	yes	User UUID

curl -X POST "$PANEL_URL/api/admin/users/$UUID/unban" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:user:updated

Responses: 200 User unbanned successfully · 400 Bad request - User is not banned or demo mode restriction · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User not found · 500 Internal server error - Failed to unban user

Users endpoints (Admin API)

Endpoints

GET/api/admin/users

GET/api/admin/users/{uuid}

GET/api/admin/users/external/{externalId}

PATCH/api/admin/users/{uuid}

DELETE/api/admin/users/{uuid}

PUT/api/admin/users

GET/api/admin/users/{uuid}/servers

GET/api/admin/users/{uuid}/vm-instances

GET/api/admin/users/{uuid}/potential-alts

DELETE/api/admin/users/{uuid}/devices

POST/api/admin/users/alt-detection/reset

DELETE/api/admin/devices

GET/api/admin/users/serverRequest/{id}

POST/api/admin/users/{uuid}/sso-token

POST/api/admin/users/{uuid}/send-email

POST/api/admin/users/{uuid}/mails/{id}/resend

POST/api/admin/users/{uuid}/verify-email

POST/api/admin/users/{uuid}/ban

POST/api/admin/users/{uuid}/unban

GET`/api/admin/users`

GET`/api/admin/users/{uuid}`

GET`/api/admin/users/external/{externalId}`

PATCH`/api/admin/users/{uuid}`

DELETE`/api/admin/users/{uuid}`

PUT`/api/admin/users`

GET`/api/admin/users/{uuid}/servers`

GET`/api/admin/users/{uuid}/vm-instances`

GET`/api/admin/users/{uuid}/potential-alts`

DELETE`/api/admin/users/{uuid}/devices`

POST`/api/admin/users/alt-detection/reset`

DELETE`/api/admin/devices`

GET`/api/admin/users/serverRequest/{id}`

POST`/api/admin/users/{uuid}/sso-token`

POST`/api/admin/users/{uuid}/send-email`

POST`/api/admin/users/{uuid}/mails/{id}/resend`

POST`/api/admin/users/{uuid}/verify-email`

POST`/api/admin/users/{uuid}/ban`

POST`/api/admin/users/{uuid}/unban`