Pterodactyl Settings

Configure integration with Pterodactyl panel including API, SSO, and server management.

Breadcrumb: System Configuration > Pterodactyl Settings

Overview

Pterodactyl Settings control how PteroCA integrates with your Pterodactyl panel for server provisioning and management. PteroCA uses the Pterodactyl API to:

• Create servers automatically

• Manage server lifecycle

• Sync server information

• Handle server suspensions

• Optional Single Sign-On (SSO) integration

Proper configuration is critical for PteroCA to function correctly.

Settings Overview

Setting	Type	CLI	Admin Panel	Description
Pterodactyl Panel URL	URL	✓	✓	URL of Pterodactyl installation
Pterodactyl API Key	Secret	✓	✓	Application API key with full permissions
Use as Client Panel	Boolean		✓	Use Pterodactyl for server management UI
SSO Enabled	Boolean		✓	Enable Single Sign-On with Pterodactyl
SSO Secret	Secret		✓	Shared secret for SSO authentication
Show Logs in Activity	Boolean		✓	Display Pterodactyl logs in server activity

Configuration via CLI Wizard

The CLI configuration wizard covers the 2 essential Pterodactyl settings during initial setup.

Run the Wizard

cd /var/www/pteroca
php bin/console pteroca:system:configure

Pterodactyl Configuration Prompts

--- Pterodactyl panel credentials ---

Pterodactyl Panel URL [https://panel.example.com]:
https://ptero.example.com

Pterodactyl Panel API Key [***]:
ptlc_****************************

Prerequisites

Before configuring:

1. Pterodactyl Panel Running:

   • Installed and accessible

   • Properly configured

2. Application API Key Created:

   • Navigate to Pterodactyl Admin Panel

   • Go to Application API

   • Create new key with all permissions

   • Copy key (shown only once)

See Pterodactyl API Configuration for detailed setup.

Configuration via Admin Panel

All 6 Pterodactyl settings can be managed through the Admin Panel.

Access Pterodactyl Settings

1. Log in to the Admin Panel

2. Navigate to Settings in the main menu

3. Click Pterodactyl

4. Update values

5. Click Save

Setting Details

Pterodactyl Panel URL

Setting Code: pterodactyl_url Field Type: URL Required: Yes Default: None

The base URL where your Pterodactyl panel is accessible.

Format:

https://ptero.example.com

Requirements:

• Must include protocol (http:// or https://)

• No trailing slash

• Must be accessible from PteroCA server

• Should be HTTPS in production

Examples:

Production:

https://panel.pterodactyl.io
https://ptero.example.com

Development:

http://localhost:8080
http://192.168.1.100

Testing Connection:

# From PteroCA server
curl -I https://ptero.example.com

Common Issues:

• Firewall blocking access

• Invalid SSL certificate

• DNS not resolving

• Panel not running

Pterodactyl API Key

Setting Code: pterodactyl_api_key Field Type: Secret (Password) Required: Yes Default: None

Application API key from Pterodactyl with full read & write permissions.

Format:

ptlc_****************************

Creating API Key:

1. Log in to Pterodactyl Admin Panel

2. Navigate to Application API (not Account API)

3. Click Create New

4. Description: PteroCA Integration

5. Select ALL permissions:

   • ✓ User Management

   • ✓ Server Management

   • ✓ Node Management

   • ✓ Allocation Management

   • ✓ Nest Management

   • ✓ Egg Management

   • ✓ Database Management

   • ✓ Location Management

6. Click Create

7. Copy key immediately (shown only once)

Required Permissions:

PteroCA requires all Application API permissions to:

• Create servers

• Assign allocations

• Manage users

• Install eggs

• Configure databases

• Handle suspensions

Security:

• Store securely

• Never expose in logs

• Rotate periodically

• Use separate key per environment

Testing API Key:

# Test API connection
curl -H "Authorization: Bearer ptlc_***" \
     -H "Accept: Application/vnd.pterodactyl.v1+json" \
     https://ptero.example.com/api/application/users

Expected response: JSON with user data

For detailed setup, see Pterodactyl API Configuration.

Use Pterodactyl Panel as Client Panel

Setting Code: pterodactyl_use_as_client_panel Field Type: Boolean (Toggle) Required: No Default: false

Redirect server management to Pterodactyl's client panel instead of PteroCA.

When Enabled:

• Server management links redirect to Pterodactyl

• Users manage servers in Pterodactyl UI

• PteroCA only handles billing and provisioning

When Disabled (Default):

• Servers managed within PteroCA

• Embedded Pterodactyl console

• Unified user experience

Use Cases for Enabling:

1. Advanced Users:

   • Users familiar with Pterodactyl

   • Need full Pterodactyl features

2. Feature Parity:

   • Pterodactyl has features not in PteroCA

   • Full file manager access needed

3. Separate Branding:

   • Game hosting on Pterodactyl

   • Billing on PteroCA

Considerations:

• Users must have accounts on both systems

• Consider enabling SSO for seamless experience

• May confuse less technical users

Pterodactyl SSO Enabled

Setting Code: pterodactyl_sso_enabled Field Type: Boolean (Toggle) Required: No Default: false

Enable Single Sign-On between PteroCA and Pterodactyl.

IMPORTANT: SSO requires the PteroCA Pterodactyl Addon to be installed and configured in your Pterodactyl panel. This setting alone is not sufficient - you must also configure the addon side. See SSO Setup Guide for complete instructions.

Prerequisites:

1. PteroCA Pterodactyl Addon installed in Pterodactyl (Required!)

2. SSO secret configured on both panels

3. Allowed origins configured

4. Both panels accessible via HTTPS

When Enabled:

• Users can click "Login to Pterodactyl" button in PteroCA

• Automatic authentication without separate login

• Seamless experience between panels

Benefits:

• Single login for both panels

• Better user experience

• Reduced support requests

• Increased security (fewer passwords)

Setup Steps:

1. Install PteroCA Pterodactyl Addon (Addon Installation)

2. Generate shared SSO secret

3. Configure SSO secret in PteroCA (this setting)

4. Configure SSO secret in Pterodactyl addon

5. Test SSO flow

Related Documentation:

• PteroCA Pterodactyl Addon Installation

• SSO Setup Guide - Complete configuration guide

• Allowed Origins - CORS configuration

Pterodactyl SSO Secret

Setting Code: pterodactyl_sso_secret Field Type: Secret (Password) Required: Only if SSO enabled Default: None

Shared secret key used to sign SSO tokens between PteroCA and Pterodactyl.

Format:

Random secure string (32+ characters recommended)

Generating SSO Secret:

# Generate secure random string
openssl rand -base64 32

Example:

7Kj9mP4nL2qR8sT5vW3xZ6cY1bN0aM4

Security:

• Must be same on both panels

• Keep absolutely confidential

• Use cryptographically random value

• Rotate periodically

Configuration:

1. Generate secret

2. Save in PteroCA: Settings → Pterodactyl → SSO Secret

3. Save in Pterodactyl addon configuration

4. Test SSO login

Never:

• Share publicly

• Commit to version control

• Reuse across environments

• Use predictable values

Show Pterodactyl Logs in Server Activity

Setting Code: show_pterodactyl_logs_in_server_activity Field Type: Boolean (Toggle) Required: No Default: false

Display Pterodactyl panel logs in PteroCA server activity feed.

When Enabled:

• Pterodactyl events appear in server timeline

• Admin actions from Pterodactyl visible

• Complete audit trail

Logged Events:

• Server power state changes

• File modifications (if tracked)

• Configuration changes

• Reinstallations

• Database creations

Use Cases:

• Comprehensive activity monitoring

• Audit compliance

• Troubleshooting

• User accountability

Considerations:

• May create verbose logs

• Requires Pterodactyl webhook configuration

• Slight performance impact

Best Practices

API Security

1. Use HTTPS:

   • Never connect to Pterodactyl over HTTP in production

   • Ensures API key transmitted securely

2. Rotate Keys:

   • Change API key periodically (quarterly recommended)

   • Rotate immediately if compromised

3. Minimum Permissions:

   • While all permissions are required, audit usage

   • Monitor API logs for anomalies

Server Lifecycle Management

1. Monitor Server Status:

   • Track server creation success/failure rates

   • Monitor suspension events

   • Review server activity logs regularly

2. Sync Regularly:

   • Keep PteroCA and Pterodactyl in sync

   • Verify server states match

   • Check for orphaned servers

3. Backup API Configuration:

   • Document API key location

   • Keep backup of configuration

   • Test failover procedures

SSO Implementation

1. Test Thoroughly:

   • Test SSO flow before enabling for users

   • Verify token generation and validation

2. Secure Secrets:

   • Use strong SSO secret

   • Store securely

   • Never expose in client-side code

3. Monitor Authentication:

   • Log SSO attempts

   • Alert on failures

   • Track unusual patterns

Integration Monitoring

1. API Health:

   • Monitor API response times

   • Track error rates

   • Set up alerts for failures

2. Sync Status:

   • Verify server data syncs correctly

   • Check for orphaned resources

   • Regular reconciliation

3. Log Review:

   • Review Pterodactyl logs regularly

   • Investigate anomalies

   • Track integration issues

Troubleshooting

API Connection Failures

Problem: Cannot connect to Pterodactyl API

Possible Causes:

• Incorrect URL

• Firewall blocking connection

• SSL certificate issues

• Pterodactyl panel down

Solutions:

1. Verify URL:

   curl -I https://ptero.example.com

2. Test API Endpoint:

   curl -H "Authorization: Bearer ptlc_***" \
        -H "Accept: Application/vnd.pterodactyl.v1+json" \
        https://ptero.example.com/api/application/users

3. Check Firewall:

   # Allow outbound HTTPS to Pterodactyl
   sudo ufw allow out 443/tcp

4. Verify SSL:

   openssl s_client -connect ptero.example.com:443

5. Check Pterodactyl Status:

   • Access Pterodactyl admin panel

   • Check server logs

   • Verify panel is running

Authentication Errors

Problem: API authentication failed

Causes:

• Invalid API key

• Expired key

• Insufficient permissions

• Wrong key type (Account vs Application)

Solutions:

1. Verify Key Format:

   • Should start with ptlc_

   • Application API key, not Account API

2. Check Permissions:

   • Log in to Pterodactyl admin

   • Verify key has ALL permissions

   • Regenerate if needed

3. Test Manually:

   curl -H "Authorization: Bearer YOUR_KEY" \
        -H "Accept: Application/vnd.pterodactyl.v1+json" \
        https://ptero.example.com/api/application/users

4. Create New Key:

   • Delete old key

   • Create fresh key with all permissions

   • Update in PteroCA

Server Creation Fails

Problem: Servers fail to provision

Causes:

• Insufficient allocations

• Egg configuration errors

• Resource limits exceeded

• Node offline

Solutions:

1. Check Allocations:

   • Verify node has available IP:Port combinations

   • Create allocations in Pterodactyl

2. Verify Egg:

   • Ensure egg exists and is configured

   • Check egg startup command

3. Review Node Status:

   • Check node is online

   • Verify Wings daemon running

4. Check Logs:

   # PteroCA logs
   tail -f var/log/prod.log | grep pterodactyl
   
   # Pterodactyl logs
   tail -f storage/logs/laravel.log

SSO Not Working

Problem: SSO login fails or redirects incorrectly

Causes:

• Addon not installed

• Secret mismatch

• Allowed origins not configured

• Token signing issues

Solutions:

1. Verify Addon Installed:

   • Check Pterodactyl admin → Addons

   • Reinstall if needed

2. Match SSO Secret:

   • Must be identical on both panels

   • Check for extra spaces/characters

3. Configure Allowed Origins:

   • Add PteroCA URL to Pterodactyl allowed origins

   • See Allowed Origins

4. Check Browser Console:

   • F12 → Console tab

   • Look for CORS errors or JWT issues

5. Test Token Generation:

   • Verify tokens are being created

   • Check token expiration

   • Validate signature

See SSO Setup Guide for detailed troubleshooting.

Suspended Server Deletion Issues

Problem: Suspended servers not deleting automatically

Causes:

• Cron scheduler not running

• Deletion disabled

• Date calculation errors

Solutions:

1. Verify Cron:

   # Check cron is configured
   crontab -l
   
   # Should include:
   * * * * * cd /var/www/pteroca && php bin/console pteroca:cron:run >> /dev/null 2>&1

2. Check Settings:

   • Navigate to Settings → General

   • Verify "Delete Suspended Servers Enabled" is ON

   • Verify "Days After Suspension" is set correctly

   • See General Settings for details

3. Manual Trigger:

   php bin/console pteroca:servers:cleanup-suspended

4. Review Logs:

   tail -f var/log/prod.log | grep cleanup

Related Settings

• General Settings - Site URL, server deletion settings

• Email Settings - SMTP configuration for Pterodactyl notifications

• Payment Settings - Server provisioning on payment

Additional Resources

• Pterodactyl Integration Overview - Complete integration guide

• API Configuration - Detailed API setup

• SSO Setup - Single Sign-On configuration

• Addon Installation - PteroCA addon for Pterodactyl

• Allowed Origins - CORS configuration

• Pterodactyl Documentation - Official Pterodactyl docs