The Users API allows you to create, view, update, and delete user accounts on the Pterodactyl Panel. Users can be assigned as server owners and can be granted administrative privileges.
List Users curl "https://panel.example.com/api/application/users" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json"
Retrieves a paginated list of all users on the Panel.
Query Parameters Number of results per page
Filter users by email address
Filter users by external identifier
Sort by field. Available: id, uuid. Prefix with - for descending order
Response Array of user objects External identifier for third-party integrations
Unique identifier for the user
Username (stored as lowercase)
User’s preferred language code (e.g., en)
Whether the user has administrator privileges
Whether two-factor authentication is enabled
ISO 8601 timestamp of creation
ISO 8601 timestamp of last update
{ "object" : "list" , "data" : [ { "object" : "user" , "attributes" : { "id" : 1 , "external_id" : null , "uuid" : "c4022c6c-9bf1-4a23-bff9-519cceb38335" , "username" : "admin" , "email" : "[email protected] " , "first_name" : "Admin" , "last_name" : "User" , "language" : "en" , "root_admin" : true , "2fa" : false , "created_at" : "2024-01-01T00:00:00+00:00" , "updated_at" : "2024-01-15T12:30:00+00:00" } } ], "meta" : { "pagination" : { "total" : 1 , "count" : 1 , "per_page" : 50 , "current_page" : 1 , "total_pages" : 1 } } }
Get User Details curl "https://panel.example.com/api/application/users/{user_id}" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json"
Retrieves details for a specific user.
Path Parameters The internal ID of the user
Query Parameters Include related resources. Available: servers
Get User by External ID curl "https://panel.example.com/api/application/users/external/{external_id}" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json"
Retrieves a user by their external identifier.
Path Parameters The external identifier of the user
Create User curl -X POST "https://panel.example.com/api/application/users" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] ", "username": "newuser", "first_name": "John", "last_name": "Doe", "password": "SecurePassword123" }'
Creates a new user account on the Panel.
Request Body User email address (must be unique)
Username (must be unique, will be converted to lowercase)
User password. If not provided, user will need to reset password
External identifier for third-party integrations (must be unique)
User’s preferred language code
Whether to grant administrator privileges
Response Returns the created user object with HTTP status 201 Created.
{ "object" : "user" , "attributes" : { "id" : 2 , "external_id" : null , "uuid" : "8d4f8c5e-2b7a-4c9d-8e1f-9a3b4c5d6e7f" , "username" : "newuser" , "email" : "[email protected] " , "first_name" : "John" , "last_name" : "Doe" , "language" : "en" , "root_admin" : false , "2fa" : false , "created_at" : "2024-03-04T00:00:00+00:00" , "updated_at" : "2024-03-04T00:00:00+00:00" }, "meta" : { "resource" : "https://panel.example.com/api/application/users/2" } }
Update User curl -X PATCH "https://panel.example.com/api/application/users/{user_id}" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] ", "username": "updateduser", "first_name": "John", "last_name": "Smith" }'
Updates an existing user’s information.
Path Parameters The internal ID of the user to update
Request Body All fields are optional. Only include fields you want to update.
Update administrator status
Response Returns the updated user object.
Delete User curl -X DELETE "https://panel.example.com/api/application/users/{user_id}" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json"
Deletes a user from the Panel. The user must not own any servers.
Path Parameters The internal ID of the user to delete
Response Returns HTTP status 204 No Content on successful deletion.
A user cannot be deleted if they currently own any servers. Transfer or delete their servers first.
