# 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](/core-configuration/pterodactyl-integration/addon-installation.md)

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:

```bash
php bin/console pteroca:system:configure
```

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**

   ```bash
   # Test Pterodactyl API connection
   php bin/console pteroca:pterodactyl:test-connection
   ```

### Check API Response

Manually test the API using curl:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Accept: Application/vnd.pterodactyl.v1+json" \
     https://panel.pterodactyl.io/api/application/users
```

Should return JSON list of users.

## Troubleshooting

### API Connection Failed

**Error:** "Cannot connect to Pterodactyl API"

**Solutions:**

1. **Verify URL is correct**

   ```bash
   curl https://panel.pterodactyl.io/api/application/users
   ```

   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**

   ```bash
   curl -H "Authorization: Bearer ptlc_YOUR_KEY" \
        https://panel.pterodactyl.io/api/application/users
   ```

### 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**

   ```bash
   cd /var/www/pterodactyl
   composer show pteroca-com/pterodactyl-addon
   ```
2. **Check API key has Users (Write) permission**
3. **Test user creation manually**

   ```bash
   curl -X POST https://panel.pterodactyl.io/api/application/users \
        -H "Authorization: Bearer ptlc_YOUR_KEY" \
        -H "Accept: Application/vnd.pterodactyl.v1+json" \
        -H "Content-Type: application/json" \
        -d '{"email":"test@example.com","username":"testuser","first_name":"Test","last_name":"User"}'
   ```

### SSL Certificate Errors

**Error:** "SSL certificate problem"

**Solutions:**

1. **Verify Pterodactyl has valid SSL**

   ```bash
   curl https://panel.pterodactyl.io
   ```
2. **Update CA certificates**

   ```bash
   sudo 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

* [Allowed Origins Configuration](/core-configuration/pterodactyl-integration/allowed-origins.md) - Enable console access
* [PteroCA Pterodactyl Addon](/core-configuration/pterodactyl-integration/addon-installation.md) - Addon documentation
* [System Configuration](/core-configuration/core-configuration.md) - Complete system setup
* [Troubleshooting](https://github.com/PteroCA-Org/pteroca-homepage/blob/docs/help-and-maintenance/troubleshooting/README.md) - Common issues


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pteroca.com/core-configuration/pterodactyl-integration/api-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.