Users

Manage user accounts on the Panel

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

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

per_page · integer · default: "50"

Number of results per page

filter[email] · string

Filter users by email address

filter[uuid] · string

Filter users by UUID

filter[username] · string

Filter users by username

filter[external_id] · string

Filter users by external identifier

sort · string

Sort by field. Available: id, uuid. Prefix with - for descending order

Response

object · string

Always list

data · array

Array of user objects

Show User Object

id · integer

Internal user ID

external_id · string | null

External identifier for third-party integrations

uuid · string

Unique identifier for the user

username · string

Username (stored as lowercase)

email · string

User email address

first_name · string

User’s first name

last_name · string

User’s last name

language · string

User’s preferred language code (e.g., en)

root_admin · boolean

Whether the user has administrator privileges

2fa · boolean

Whether two-factor authentication is enabled

created_at · string

ISO 8601 timestamp of creation

updated_at · string

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": "[e-mail]",
        "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

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

user_id · integer · required

The internal ID of the user

Query Parameters

include · string

Include related resources. Available: servers

Get User by External ID

cURL

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

external_id · string · required

The external identifier of the user

Create User

cURL

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": "[e-mail]",
    "username": "newuser",
    "first_name": "John",
    "last_name": "Doe",
    "password": "SecurePassword123"
  }'

Creates a new user account on the Panel.

Request Body

email · string · required

User email address (must be unique)

username · string · required

Username (must be unique, will be converted to lowercase)

first_name · string · required

User’s first name

last_name · string · required

User’s last name

password · string

User password. If not provided, user will need to reset password

external_id · string

External identifier for third-party integrations (must be unique)

language · string · default: "en"

User’s preferred language code

root_admin · boolean · default: false

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": "[e-mail]",
    "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

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": "[e-mail]",
    "username": "updateduser",
    "first_name": "John",
    "last_name": "Smith"
  }'

Updates an existing user’s information.

Path Parameters

user_id · integer · required

The internal ID of the user to update

Request Body

All fields are optional. Only include fields you want to update.

email · string

New email address

username · string

New username

first_name · string

New first name

last_name · string

New last name

password · string

New password

external_id · string

New external identifier

language · string

New language preference

root_admin · boolean

Update administrator status

Response

Returns the updated user object.

Delete User

cURL

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

user_id · integer · required

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.