v0.6.0

API Configuration

Configure API integration between PteroCA and Pterodactyl panel.

Overview

PteroCA integrates with Pterodactyl to provide server management functionality. This integration requires:

  1. PteroCA addon installed in Pterodactyl

  2. Application API key with full permissions

  3. Correct API configuration in PteroCA

Prerequisites

  • Pterodactyl panel installed and running

  • Admin access to Pterodactyl panel

  • Composer access to Pterodactyl server

Step 1: Install PteroCA Addon

The PteroCA addon is required for full functionality. It enables Client API key creation through the API, which standard Pterodactyl doesn't support.

Complete installation guide: PteroCA Pterodactyl Addon

The addon installation guide includes:

  • Detailed installation steps with verification

  • Post-installation configuration

  • Version compatibility information

  • Troubleshooting common issues

  • Security best practices

Once the addon is installed and verified, proceed to create the API key below.

Step 2: Create API Key

Create an Application API key in Pterodactyl with full permissions.

Via Pterodactyl Admin Panel

  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" (or any identifying name)

    • 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 - It will only be shown once!

    • Format: ptlc_****************************

    • Store securely - you'll need this for PteroCA configuration

Required Permissions

The API key must have 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)

Missing any permission will cause PteroCA features to fail.

Step 3: Configure in PteroCA

Add the Pterodactyl API credentials to PteroCA.

Method 1: Via System Configuration Command

During initial setup, run:

When prompted for Pterodactyl credentials:

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

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

Method 2: Via 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

Verifying API Connection

Test API Connection

After configuration, verify the connection works:

  1. Check Admin Dashboard

    • Navigate to Admin Dashboard

    • Look for Pterodactyl connection status

  2. Try Creating a Server

    • Go to Store/Shop

    • Configure and purchase a server

    • Check if server is created in Pterodactyl

  3. Test via CLI

Check API Response

Manually test the API using curl:

Should return JSON list of users.

Troubleshooting

API Connection Failed

Error: "Cannot connect to Pterodactyl API"

Solutions:

  1. Verify URL is correct

    Should return 401 (unauthorized) not connection error

  2. Check API key format

    • Should start with ptlc_

    • No extra spaces or characters

    • Full key copied (not truncated)

  3. Verify API key has permissions

    • Check in Pterodactyl Admin → Application API

    • Ensure ALL permissions are checked

  4. Test with curl

Server Creation Fails

Error: "Failed to create server in Pterodactyl"

Possible Causes:

  1. Missing API permissions

    • Verify API key has Servers (Write) permission

  2. Invalid egg/nest configuration

    • Check product configuration in PteroCA

    • Verify egg exists in Pterodactyl

  3. Allocation not available

    • Ensure node has available allocations

    • Check allocation is not already in use

  4. Node offline or full

    • Verify node status in Pterodactyl

    • Check available disk/memory

User Synchronization Issues

Error: "Cannot create Pterodactyl user"

Solutions:

  1. Verify addon is installed

  2. Check API key has Users (Write) permission

  3. Test user creation manually

SSL Certificate Errors

Error: "SSL certificate problem"

Solutions:

  1. Verify Pterodactyl has valid SSL

  2. Update CA certificates

  3. Check certificate is not self-signed

    • Use Let's Encrypt or valid SSL certificate

    • Self-signed certificates may cause issues

Security Best Practices

API Key Security

  1. Never commit API keys to version control

    • Add .env to .gitignore

    • Use environment variables

  2. Regenerate compromised keys immediately

    • Revoke old key in Pterodactyl

    • Create new key

    • Update in PteroCA

  3. Use separate keys for testing

    • Development environment: separate API key

    • Production environment: dedicated API key

  4. Monitor API usage

    • Review API logs in Pterodactyl

    • Watch for unusual activity

Network Security

  1. Use HTTPS only

    • Never use HTTP for API communication

    • Encrypt all traffic

  2. Firewall rules

    • Allow API traffic between PteroCA and Pterodactyl

    • Block unnecessary external access

  3. Keep software updated

    • Regularly update Pterodactyl

    • Update PteroCA addon

    • Apply security patches promptly

API Rate Limiting

Pterodactyl has API rate limits to prevent abuse:

  • Default: 240 requests per minute

  • Burst: Up to 1000 requests (with cooldown)

If you hit rate limits:

  1. Reduce polling frequency in PteroCA

  2. Implement caching for frequently accessed data

  3. Use webhooks instead of polling (when available)

  4. Contact Pterodactyl admin to adjust limits if needed

Related Guides

PreviousPteroCA Pterodactyl AddonNextAllowed Origins

Last updated