Skip to main content
Version: v1.0+

User Management

The Application API User Management endpoints allow administrators to manage all users in the panel. These endpoints provide full CRUD (Create, Read, Update, Delete) operations for user accounts.

Administrative Access Required

These endpoints require administrative privileges and should only be used by trusted applications with proper authentication.

Authentication

All Application API requests require authentication using an API key with appropriate permissions:

Authorization: Bearer YOUR_APPLICATION_API_KEY
Accept: Application/vnd.pterodactyl.v1+json
Content-Type: application/json

List All Users

Retrieve a paginated list of all users in the panel.

GET /api/application/users

Query Parameters

ParameterTypeDescriptionDefault
pageintegerPage number for pagination1
per_pageintegerResults per page (1-100)50
filter[email]stringFilter by email address-
filter[uuid]stringFilter by user UUID-
filter[username]stringFilter by username-
filter[external_id]stringFilter by external ID-
sortstringSort field (id, uuid, username, email, created_at, updated_at)id
includestringInclude relationships (servers)-

Example Request

curl "https://your-panel.com/api/application/users?include=servers&per_page=25" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Example Response

{
"object": "list",
"data": [
{
"object": "user",
"attributes": {
"id": 1,
"external_id": null,
"uuid": "c4022c6c-9bf1-4a23-bff9-519cceb38335",
"username": "system",
"email": "[email protected]",
"first_name": "System",
"last_name": "Administrator",
"language": "en",
"root_admin": true,
"2fa": false,
"created_at": "2023-01-15T10:26:32+00:00",
"updated_at": "2023-01-15T10:26:32+00:00"
},
"relationships": {
"servers": {
"object": "list",
"data": []
}
}
}
],
"meta": {
"pagination": {
"total": 1,
"count": 1,
"per_page": 50,
"current_page": 1,
"total_pages": 1,
"links": {}
}
}
}

Get User Details

Retrieve detailed information about a specific user.

GET /api/application/users/{user}

Path Parameters

ParameterTypeDescription
userintegerUser ID

Query Parameters

ParameterTypeDescription
includestringInclude relationships (servers)

Example Request

GET /api/application/users/{user}
curl "https://your-panel.com/api/application/users/1?include=servers" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Example Response

{
"object": "user",
"attributes": {
"id": 1,
"external_id": null,
"uuid": "c4022c6c-9bf1-4a23-bff9-519cceb38335",
"username": "system",
"email": "[email protected]",
"first_name": "System",
"last_name": "Administrator",
"language": "en",
"root_admin": true,
"2fa": false,
"created_at": "2023-01-15T10:26:32+00:00",
"updated_at": "2023-01-15T10:26:32+00:00"
},
"relationships": {
"servers": {
"object": "list",
"data": []
}
}
}

Create New User

Create a new user account in the panel.

POST /api/application/users

Request Body

FieldTypeRequiredDescription
emailstringYesUser's email address (must be unique)
usernamestringYesUsername (must be unique)
first_namestringYesUser's first name
last_namestringYesUser's last name
passwordstringNoUser's password (if not provided, user must reset)
languagestringNoUser's preferred language (default: en)
root_adminbooleanNoWhether user has administrative privileges
external_idstringNoExternal ID for integration purposes

Example Request

curl -X POST "https://your-panel.com/api/application/users" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"username": "newuser",
"first_name": "New",
"last_name": "User",
"password": "secure_password_123",
"language": "en",
"root_admin": false
}'

Example Response

{
"object": "user",
"attributes": {
"id": 2,
"external_id": null,
"uuid": "f3b21b3e-4c5d-4f8e-9a1b-2c3d4e5f6789",
"username": "newuser",
"email": "[email protected]",
"first_name": "New",
"last_name": "User",
"language": "en",
"root_admin": false,
"2fa": false,
"created_at": "2024-01-20T14:30:45+00:00",
"updated_at": "2024-01-20T14:30:45+00:00"
}
}

Update User

Update an existing user's information.

PATCH /api/application/users/{user}

Path Parameters

ParameterTypeDescription
userintegerUser ID

Request Body

FieldTypeRequiredDescription
emailstringNoUser's email address
usernamestringNoUsername
first_namestringNoUser's first name
last_namestringNoUser's last name
passwordstringNoNew password
languagestringNoUser's preferred language
root_adminbooleanNoAdministrative privileges
external_idstringNoExternal ID for integration

Example Request

curl -X PATCH "https://your-panel.com/api/application/users/2" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Updated",
"last_name": "Name",
"language": "fr"
}'

Example Response

{
"object": "user",
"attributes": {
"id": 2,
"external_id": null,
"uuid": "f3b21b3e-4c5d-4f8e-9a1b-2c3d4e5f6789",
"username": "newuser",
"email": "[email protected]",
"first_name": "Updated",
"last_name": "Name",
"language": "fr",
"root_admin": false,
"2fa": false,
"created_at": "2024-01-20T14:30:45+00:00",
"updated_at": "2024-01-20T15:45:30+00:00"
}
}

Delete User

Delete a user account from the panel. This action is irreversible.

DELETE /api/application/users/{user}

Path Parameters

ParameterTypeDescription
userintegerUser ID

Example Request

curl -X DELETE "https://your-panel.com/api/application/users/2" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Response

Returns HTTP 204 No Content on successful deletion.

Error Responses

Common Error Codes

Status CodeDescription
400Bad Request - Invalid input data
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - User does not exist
422Validation Error - Invalid field values
429Too Many Requests - Rate limit exceeded

Example Error Response

{
"errors": [
{
"code": "ValidationException",
"status": "422",
"detail": "The email field is required.",
"source": {
"field": "email"
}
}
]
}

Best Practices

Security Considerations

  1. API Key Protection: Store API keys securely and never expose them in client-side code
  2. HTTPS Only: Always use HTTPS for API requests
  3. Rate Limiting: Implement proper rate limiting to avoid hitting API limits
  4. Input Validation: Validate all input data before sending API requests
  5. Error Handling: Implement comprehensive error handling for all API calls

Performance Tips

  1. Pagination: Use pagination for large datasets
  2. Filtering: Apply filters to reduce response size
  3. Selective Fields: Use include parameter only when needed
  4. Caching: Implement caching strategies for frequently accessed data
  5. Bulk Operations: Use bulk operations when available

Integration Examples

// User management service example
class UserService {
constructor(apiKey, baseUrl) {
this.apiKey = apiKey;
this.baseUrl = baseUrl;
this.headers = {
'Authorization': `Bearer ${apiKey}`,
'Accept': 'Application/vnd.pterodactyl.v1+json',
'Content-Type': 'application/json'
};
}

async getAllUsers(options = {}) {
const params = new URLSearchParams(options);
const response = await fetch(`${this.baseUrl}/api/application/users?${params}`, {
headers: this.headers
});
return response.json();
}

async createUser(userData) {
const response = await fetch(`${this.baseUrl}/api/application/users`, {
method: 'POST',
headers: this.headers,
body: JSON.stringify(userData)
});
return response.json();
}

async updateUser(userId, updateData) {
const response = await fetch(`${this.baseUrl}/api/application/users/${userId}`, {
method: 'PATCH',
headers: this.headers,
body: JSON.stringify(updateData)
});
return response.json();
}

async deleteUser(userId) {
const response = await fetch(`${this.baseUrl}/api/application/users/${userId}`, {
method: 'DELETE',
headers: this.headers
});
return response.status === 204;
}
}

Rate Limiting

The Application API implements rate limiting to prevent abuse:

  • Default Limit: 240 requests per minute per API key
  • Burst Limit: Up to 10 requests per second
  • Headers: Response includes rate limit headers
X-RateLimit-Limit: 240
X-RateLimit-Remaining: 235
X-RateLimit-Reset: 1642686400

Source Code References

Controllers and Routes

Method: UserController@index (List Users)
Route: GET /api/application/users
Source: UserController.php

Method: UserController@view (Get User)
Route: GET /api/application/users/{user}
Source: UserController.php

Method: UserController@store (Create User)
Route: POST /api/application/users
Source: UserController.php

Method: UserController@update (Update User)
Route: PATCH /api/application/users/{user}
Source: UserController.php

Method: UserController@delete (Delete User)
Route: DELETE /api/application/users/{user}
Source: UserController.php

Services

User Creation Service: UserCreationService.php
User Update Service: UserUpdateService.php
User Deletion Service: UserDeletionService.php

Models and Validation

User Model: User.php
User Store Request: StoreUserRequest.php
User Update Request: UpdateUserRequest.php

Route Definitions

Application Routes: api-application.php - Lines 45-55

For detailed implementation and the latest updates, refer to the Pterodactyl Panel repository.