v0.6.0

PteroCA Pterodactyl Addon

PteroCA Pterodactyl Addon is a plugin designed to integrate Pterodactyl with the PteroCA panel.

1. Overview

The PteroCA Pterodactyl Addon is the official plugin for the PteroCA project, providing direct and seamless integration between the Pterodactyl game server management panel and the PteroCA client & billing panel.

This addon is required for PteroCA to function properly. Without it, the panel will not be able to communicate with your Pterodactyl installation, and core features such as server synchronization, Single Sign-On (SSO), and automated resource management will not work.

What is the Addon?

The addon is a server-side extension that runs within your Pterodactyl Panel installation. It extends Pterodactyl's Application API with custom endpoints that PteroCA needs for deep integration.

Installation Location: The addon is installed on your Pterodactyl Panel server (not on PteroCA server).

Technical Details:

  • Type: Pterodactyl Extension/Plugin

  • Installation Method: Composer package

  • Package Name: pteroca-com/pterodactyl-addon

  • API Integration: Extends /api/application with custom endpoints

2. Key Features

Installing the addon unlocks full integration between PteroCA and Pterodactyl, including:

Core Integration Features

  • Full Server Management from PteroCA Access server consoles, start/stop/restart servers, monitor live CPU, RAM, and disk usage, and manage startup variables without leaving PteroCA.

  • Automatic Account & Server Synchronization When a user or server is created in PteroCA, it is automatically created and linked in Pterodactyl — and vice versa.

  • Single Sign-On (SSO) Users can open their Pterodactyl panel directly from PteroCA without re-entering credentials (if SSO is enabled in settings).

  • Extended API Capabilities Adds API endpoints that PteroCA needs for package assignments, resource updates, server variable management, and automated deployments.

  • Unified User Experience Eliminates the need for users to manually switch between separate panels to manage their services.

Technical Features

  • Version Information Endpoint Provides GET /api/application/pteroca/version for compatibility checking

  • Compatibility Verification PteroCA validates addon presence during first-time setup

  • Future Extensibility Foundation for additional custom endpoints as PteroCA evolves

  • Admin Dashboard Integration Addon version displayed in PteroCA Admin Panel (System Information widget)

3. Requirements

Before installing the addon, make sure your environment meets the following requirements:

Pterodactyl Requirements

  • Pterodactyl Panel: v1.11.0 or later (recommended: latest stable version)

  • PHP: 8.1 or higher (8.2+ recommended)

  • Composer: Installed and accessible from command line

  • MySQL/MariaDB: As required by Pterodactyl

Access Requirements

  • File system access: SSH or SFTP to Pterodactyl panel server

  • Command line access: Ability to run composer and artisan commands

  • Sudo/root access: May be required for file permissions

Network Requirements

  • API Access: PteroCA server must be able to reach Pterodactyl API

  • HTTPS: Secure connection between PteroCA and Pterodactyl (recommended)

  • Firewall: Allow API traffic between servers

PteroCA Requirements

  • PteroCA Panel: Version matching the addon version

  • Application API Key: Full permissions (created after addon installation)

4. Installation

Step 1: Navigate to Pterodactyl Directory

Connect to your Pterodactyl Panel server and navigate to the root directory:

Replace /var/www/pterodactyl with your actual Pterodactyl installation path if different.

Step 2: Install via Composer

Install the addon using Composer:

What this does:

  • Downloads the addon package from Packagist

  • Installs dependencies

  • Registers the addon with Pterodactyl

  • Makes custom API endpoints available

Expected output:

Why This Plugin is Essential

This addon enables the creation of Client API Keys through the API interface — something not possible in a standard Pterodactyl installation. These keys are required for proper server management in PteroCA.

Step 3: Clear and Rebuild Cache

Clear Pterodactyl's cache to ensure the addon is properly loaded:

What this clears:

  • Route cache

  • Configuration cache

  • View cache

  • Bootstrap cache

This step is optional but highly recommended after installation or update to prevent caching issues.

Step 4: Verify Installation

Confirm the addon is installed correctly:

Expected output:

If you see package information, the addon is installed successfully.

Step 5: Test API Endpoint

Test that the addon's custom endpoint is accessible:

Expected response:

If you receive this response, the addon is working correctly.

5. Post-Installation Configuration

After installing the addon, you need to configure the API connection in PteroCA.

Create Application API Key

  1. Log into Pterodactyl Panel as administrator

  2. Navigate to Admin → Application API

  3. Click "Create New"

  4. Configure the API key:

    • Description: "PteroCA Integration"

    • Permissions: Select ALL read & write permissions:

      • ✅ Users (Read & Write)

      • ✅ Nodes (Read & Write)

      • ✅ Allocations (Read & Write)

      • ✅ Servers (Read & Write)

      • ✅ Nests (Read & Write)

      • ✅ Eggs (Read & Write)

      • ✅ Locations (Read & Write)

  5. Click "Create Credentials"

  6. Copy the API key (format: ptlc_****) - it's shown only once!

Configure in PteroCA

Method 1: System Configuration Wizard (First-time setup)

When prompted:

  • Pterodactyl Panel URL: https://panel.pterodactyl.io

  • Pterodactyl API Key: ptlc_****************************

Method 2: Admin Panel (After installation)

  1. Navigate to Settings → Pterodactyl

  2. Update:

    • Panel URL: Your Pterodactyl panel URL

    • API Key: Your Application API key

  3. Click Save

Verify PteroCA Connection

  1. Check Admin Dashboard

    • Navigate to PteroCA Admin Panel → Dashboard

    • Look for "System Information" widget

    • Should display "PteroCA Pterodactyl Addon version: X.Y.Z"

  2. Test Server Creation

    • Go to PteroCA Shop

    • Purchase a test server

    • Verify server appears in both PteroCA and Pterodactyl

6. What the Addon Does

Understanding the addon's functionality helps with troubleshooting and maintenance.

Custom API Endpoints

The addon extends Pterodactyl's Application API with custom endpoints:

Base API URL:

Custom Endpoint Added:

Endpoint Details:

  • Authentication: Bearer token (Application API key)

  • Response Format: JSON

  • Purpose: Version checking and compatibility verification

Integration Points

User Synchronization:

  • PteroCA creates users in Pterodactyl via API

  • User entities track: pterodactylUserId and pterodactylUserApiKey

  • Client API keys generated for each user

Server Synchronization:

  • PteroCA creates/manages servers via API

  • Server entities track: pterodactylServerId and pterodactylServerIdentifier

  • Real-time status updates and resource monitoring

Single Sign-On (SSO):

  • JWT-based authentication between panels

  • Configurable SSO secret key

  • Optional feature (can be enabled/disabled)

Pterodactyl API Endpoints Used

PteroCA uses these standard Pterodactyl endpoints (no addon modification):

User Management:

  • GET /api/application/users - List users

  • POST /api/application/users - Create user

  • PUT /api/application/users/{id} - Update user

  • DELETE /api/application/users/{id} - Delete user

Server Management:

  • GET /api/application/servers - List servers

  • GET /api/application/servers/{id} - Get server details

  • POST /api/application/servers - Create server

  • POST /api/application/servers/{id}/suspend - Suspend server

  • POST /api/application/servers/{id}/unsuspend - Resume server

  • DELETE /api/application/servers/{id} - Delete server

Resource Discovery:

  • GET /api/application/nests - List nests (game categories)

  • GET /api/application/nests/{id}/eggs - List eggs (game versions)

  • GET /api/application/nodes - List nodes (physical servers)

  • GET /api/application/nodes/{id}/allocations - List port allocations

7. Updating the Addon

Keep the addon updated to ensure compatibility and receive bug fixes.

Check Current Version

Method 1: PteroCA Admin Dashboard

  1. Navigate to Admin Panel → Dashboard

  2. Find "System Information" widget

  3. Look for "PteroCA Pterodactyl Addon version"

Method 2: API Request

Method 3: Composer

Check for Updates

PteroCA automatically checks for addon updates and displays warnings in the Admin Panel if an update is available.

Manual check:

Update Process

  1. Navigate to Pterodactyl directory:

  1. Update the package:

Expected output:

  1. Clear cache:

  1. Verify new version:

Version Compatibility

PteroCA and Addon Versions:

  • Addon version should match or be compatible with PteroCA version

  • Major version mismatches may cause issues

  • PteroCA displays warnings if addon is outdated

Pterodactyl Compatibility:

  • Addon is tested with Pterodactyl 1.11.0+

  • Typically maintains backward compatibility with recent versions

  • Check addon release notes for specific Pterodactyl version requirements

Update Recommendations:

  • Update addon when updating PteroCA

  • Test updates in staging environment first

  • Keep both PteroCA and addon on latest stable versions

8. Troubleshooting

Common issues and solutions when working with the addon.

Addon Not Detected During Setup

Symptoms: PteroCA setup fails with error: "API Connection has been established, but PteroCA Pterodactyl Addon is not installed on your Pterodactyl panel."

Causes:

  • Addon not installed on Pterodactyl

  • Addon installed but cache not cleared

  • Wrong Pterodactyl URL

  • API endpoint not accessible

Solutions:

  1. Verify addon is installed:

If not installed, run:

  1. Clear Pterodactyl cache:

  1. Test addon endpoint manually:

If you get 404, addon is not properly installed.

  1. Check Pterodactyl logs:

Cannot Log In to PteroCA

Symptoms: Users cannot log in to PteroCA after registration.

Cause: Addon not installed when user was created, preventing Client API key generation.

Solution:

  1. Install the addon (if not already installed)

  2. Recreate the user:

Follow prompts to create user with admin privileges.

  1. Or update existing user:

SSO Not Working

Symptoms: Users redirected to Pterodactyl see login page instead of being automatically logged in.

Causes:

  • SSO not enabled in PteroCA settings

  • SSO secret key not configured

  • Pterodactyl not configured to accept SSO

  • Token expiration issues

Solutions:

  1. Enable SSO in PteroCA:

    • Navigate to Settings → Pterodactyl

    • Enable "Single Sign-On (SSO)"

    • Set SSO secret key (must match Pterodactyl)

    • Click Save

  2. Configure Pterodactyl:

    • Check Pterodactyl .env file

    • Ensure SSO configuration matches PteroCA

    • Restart Pterodactyl services if needed

  3. Verify JWT configuration:

    • PteroCA uses JWT tokens for SSO

    • Check token validity period

    • Ensure clocks are synchronized (NTP)

Servers Not Visible in PteroCA

Symptoms: Servers exist in Pterodactyl but don't appear in PteroCA.

Causes:

  • API connection misconfigured

  • Wrong API URL or key

  • API key lacks permissions

  • Server synchronization failed

Solutions:

  1. Verify API configuration:

    • Settings → Pterodactyl

    • Check Panel URL (must be full URL with https://)

    • Check API key is correct

  2. Test API connection:

Should return JSON list of servers.

  1. Check API key permissions:

    • Pterodactyl Admin → Application API

    • Verify key has Servers (Read) permission

    • Recreate key with full permissions if needed

  2. Force server sync:

Addon Errors After Update

Symptoms: Addon stops working after updating PteroCA or Pterodactyl.

Causes:

  • Version mismatch between PteroCA and addon

  • Breaking changes in API

  • Cache not cleared

Solutions:

  1. Check version compatibility:

    • Compare PteroCA version with addon version

    • Check addon release notes for compatibility info

  2. Update addon to match PteroCA:

  1. Rollback if needed:

  1. Check error logs:

API Rate Limiting

Symptoms: Some operations fail with "Too Many Requests" (429) errors.

Cause: Pterodactyl's API rate limiting (default: 240 requests/minute).

Solutions:

  1. Reduce polling frequency in PteroCA

  2. Implement request caching for frequently accessed data

  3. Spread operations over time instead of bulk requests

  4. Increase rate limits in Pterodactyl (if you control it):

    • Edit .env file

    • Adjust API_RATE_LIMIT setting

    • Restart services

SSL Certificate Errors

Symptoms: "SSL certificate problem" or "certificate verify failed" errors.

Causes:

  • Self-signed certificate

  • Expired certificate

  • Certificate chain issues

Solutions:

  1. Use valid SSL certificate:

    • Let's Encrypt (free)

    • Commercial SSL provider

    • Don't use self-signed in production

  2. Update CA certificates:

  1. Test certificate:

Look for certificate validation in output.

9. Security Best Practices

API Key Security

Storage:

  • Never commit API keys to version control

  • Store keys in .env files (excluded from git)

  • Use environment variables in production

Access Control:

  • Limit API key to necessary permissions only

  • Create separate keys for dev/staging/production

  • Rotate keys periodically (every 90 days recommended)

Monitoring:

  • Review API logs regularly for unusual activity

  • Monitor for failed authentication attempts

  • Set up alerts for suspicious patterns

Network Security

HTTPS Only:

  • Always use HTTPS for API communication

  • Never transmit API keys over HTTP

  • Enforce TLS 1.2 or higher

Firewall Configuration:

  • Allow API traffic only between PteroCA and Pterodactyl servers

  • Block unnecessary external access to Pterodactyl API

  • Use IP whitelisting if possible

Rate Limiting:

  • Keep Pterodactyl's default rate limits

  • Monitor for abuse or DDoS attempts

  • Adjust limits only if necessary

Update Management

Keep Software Updated:

  • Update Pterodactyl regularly

  • Update PteroCA addon when new versions release

  • Apply security patches promptly

Backup Before Updates:

  • Backup Pterodactyl database before major updates

  • Backup PteroCA database before updates

  • Test updates in staging environment first

10. Source Code & Support

Source Code

The addon is fully open-source and available at:

GitHub Repository: https://github.com/pteroca-com/pterodactyl-addon

Packagist: https://packagist.org/packages/pteroca-com/pterodactyl-addon

License: MIT License

Getting Help

If you experience any issues or need assistance:

Community Support:

Commercial Support:

  • Contact PteroCA team for enterprise support options

  • Priority support available for hosting providers

11. Related Documentation

Pterodactyl Integration:

PteroCA Configuration:

Troubleshooting:

Installation Complete!

With the addon installed and configured, your PteroCA panel can now fully manage Pterodactyl servers. Users will have a seamless experience across both panels!

PreviousPterodactyl IntegrationNextAPI Configuration

Last updated