Skip to main content
Pterodactyl uses API keys for authentication. Different API key types provide access to different parts of the API.

​
API Key Types

​
Application API Keys

Application API keys provide administrative access to the Panel and are used with the Application API. Key Prefix: ptla_ Creating Application Keys:
  1. Navigate to the Admin panel
  2. Go to Application API in the sidebar
  3. Click Create New
  4. Set permissions for each resource type
  5. Copy the generated key (shown only once)
Permissions: Each Application API key has granular permissions:
  • None (0) - No access
  • Read (1) - Read-only access
  • Read & Write (2) - Create and modify
  • Read, Write & Delete (3) - Full access
Resources include:
  • Users
  • Nodes
  • Allocations
  • Servers
  • Locations
  • Nests
  • Eggs
  • Database Hosts
  • Server Databases

​
Client API Keys

Client API keys provide user-level access and are used with the Client API. Key Prefix: ptlc_ Creating Client Keys:
  1. Go to Account Settings
  2. Navigate to API Credentials
  3. Click Create API Key
  4. Optionally set allowed IP addresses
  5. Provide a description
  6. Copy the generated key (shown only once)
Permissions: Client API keys inherit the permissions of the user who created them. If a user has access to multiple servers, the API key can manage all of them. Admin Client Keys: Client API keys created by administrator accounts can access the Application API endpoints while maintaining client API functionality.

​
Making Authenticated Requests

​
Using Bearer Token

Include your API key in the Authorization header: 
curl -X GET "https://panel.example.com/api/application/users" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ptla_yourapikeyhere"

​
Required Headers

All API requests must include: 
Authorization: Bearer {api_key}
Accept: application/json
Content-Type: application/json

​
API Key Structure

API keys consist of two parts:
  1. Identifier (16 characters) - Prefix + random string
  2. Token (32 characters) - Encrypted and stored in database
The full key format is: {prefix}_{identifier}{token} Example: 
ptla_1234567890abcdef0123456789abcdef0123456789abcdef
     ^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      Identifier              Token

​
IP Restrictions

Client API keys support IP address restrictions:
  • Specify allowed IP addresses (comma-separated)
  • Supports CIDR notation (e.g., 192.168.1.0/24)
  • Leave blank to allow all IPs
Example Configuration: 
{
  "allowed_ips": [
    "192.168.1.100",
    "10.0.0.0/8"
  ]
}

​
Key Expiration

API keys can be configured with an expiration date:
  • Set expires_at timestamp when creating keys
  • Expired keys will be rejected automatically
  • Keys track last usage via last_used_at field

​
Security Best Practices

API keys provide full access to your Panel or account. Treat them like passwords.
  1. Never commit API keys to version control
  2. Use environment variables to store keys
  3. Rotate keys regularly, especially after team member changes
  4. Use IP restrictions when possible
  5. Grant minimum required permissions for Application API keys
  6. Delete unused keys immediately
  7. Monitor key usage via last_used_at field
  8. Set expiration dates for temporary integrations

​
Key Limits

Users are limited to 25 API keys per account to prevent abuse.

​
Example: Creating a Server

curl -X POST "https://panel.example.com/api/application/servers" \
  -H "Authorization: Bearer ptla_yourapikeyhere" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Game Server",
    "user": 1,
    "egg": 1,
    "docker_image": "quay.io/pterodactyl/core:java",
    "startup": "java -Xms128M -Xmx1024M -jar server.jar",
    "environment": {},
    "limits": {
      "memory": 1024,
      "swap": 0,
      "disk": 5120,
      "io": 500,
      "cpu": 100
    },
    "feature_limits": {
      "databases": 1,
      "backups": 1
    },
    "allocation": {
      "default": 1
    }
  }'

​
Troubleshooting

​
401 Unauthorized

  • Verify the API key is correct
  • Check that the key hasn’t expired
  • Ensure proper Authorization header format

​
403 Forbidden

  • For Application API: Check resource permissions
  • For Client API: Verify access to the requested server
  • Check IP restrictions if configured

​
Invalid API Key Format

  • Ensure no extra spaces or line breaks
  • Verify the correct prefix (ptla_ or ptlc_)
  • Check that the full key was copied

Build docs developers (and LLMs) love

Get started for freeTalk to us