Pterodactyl Api Addon Laravel Package

Getting Started

This addon extends Pterodactyl Panel's Application API (the admin-side API authenticated with an Authorization: Bearer <app-key> header) so you can mint Client API keys for a user without touching the panel UI. That's the core value: the stock Application API can create users, servers, and nodes, but it can't hand you a client token you can pass to another service.

Minimal setup

1. Confirm your panel version first. Pterodactyl addons live under the panel's addons/ directory and are auto-discovered by the panel's service-provider loader — there is no config/app.php registration step. Check the repo's composer.json constraints against your panel version before anything else; Pterodactyl 1.x addons are tightly coupled to the panel's Laravel version.
2. Install into the panel root (or drop the package into addons/rene-roscher/pterodactyl-api-addon and run composer dump-autoload from the panel root if you're vendoring it).
3. Run the panel's standard post-change commands: php artisan route:clear, php artisan config:clear, and if the addon ships migrations, php artisan migrate --force.
4. Read the source before you wire it up. With a small package like this the routes file and controller are the real documentation. Run php artisan route:list --path=api and look for the new endpoints under the application API prefix — that tells you the exact verb, URI, and parameter names faster than any README.
5. Create an Application API key in Admin → Application API with the permissions you need (at minimum user read/write). Store the identifier + key pair like any other secret.

First use case

The canonical one: an external billing or control panel provisions a customer. Your backend calls the Application API to create the Pterodactyl user, then calls this addon's endpoint to generate a client API key for that user, then stores the token so your frontend can talk to the Client API (/api/client/...) on the user's behalf — listing servers, sending power actions, reading resources. Without this addon, that last step is impossible via API.

Implementation Patterns

Wrap it in a service class, not raw HTTP scattered around. You'll almost always call this from one place: user provisioning. Build a small PterodactylProvisioner that composes user creation + key generation and returns a DTO.

class PterodactylProvisioner
{
    public function __construct(private PterodactylClient $client) {}

    public function provision(string $email, string $username): ProvisionedUser
    {
        $user = $this->client->post('/api/application/users', [
            'email' => $email,
            'username' => $username,
            'first_name' => 'Provisioned',
            'last_name' => 'User',
        ]);

        $key = $this->client->post("/api/application/users/{$user['attributes']['id']}/api-keys", [
            'description' => "billing-panel-{$email}",
        ]);

        return new ProvisionedUser($user['attributes']['id'], $key['attributes']['identifier'], $key['meta']['secret_token']);
    }
}

Expect a two-part token. Pterodactyl client keys are an identifier plus a secret_token; the usable client credential is identifier + secret_token joined in the panel's expected format. Whatever the endpoint returns, persist both halves and read the exact shape from the controller before you build a database schema around it.

Idempotency matters more than you think. Provisioning is often retried by queues and webhooks. Before creating a key, list existing keys for the user (or track them locally) and reuse rather than multiplying tokens. A user with fifteen stale keys is a support ticket.

Integrate via Laravel's HTTP client when calling from inside the panel. If you're writing a panel-side job or command (not an external service), use Http::withToken(config('services.pterodactyl.key'))->baseUrl(config('app.url')) and hit the local API — it's simpler than reimplementing auth, and it exercises the same code path your external clients use.

Use it as an onboarding trigger, not a per-request operation. Token creation should happen once at account creation, not every time a user logs into your frontend. Cache the token server-side and hand your frontend a short-lived session credential of your own, keeping the panel token off the client entirely.

Pair with webhooks/events for deprovisioning. Pterodactyl fires events on user deletion; hook into them to revoke keys in your own system so you're not holding tokens for users that no longer exist.

Gotchas and Tips

The Application API key is god-mode. Anyone holding it can create servers and users across the panel. Never ship it to a browser, never put it in a frontend config, and rotate it if it leaks. The tokens this addon creates are less dangerous but still grant full client-API access as that user.

The secret is returned once. Pterodactyl does not let you retrieve a key's secret after creation — only the identifier. If your persistence step fails after the API call succeeds, that token is dead weight. Store it before you respond to your own caller, and treat a failed write as a reason to revoke and retry.

Route and config caching will bite you. Pterodactyl ships with cached routes in production. A newly installed addon whose endpoints 404 almost always means php artisan route:clear and config:clear weren't run, or the panel's config cache was built before the addon registered its provider. Check php artisan route:list --path=api first, every time.

Addon discovery is fragile across upgrades. Pterodactyl minor upgrades have historically reshuffled how addons are loaded and which composer.json constraints pass. Pin your panel version, and re-test after every panel upgrade. With a small, low-star package like this, assume the maintainer isn't tracking upstream releases day-to-day — verify before you upgrade the panel.

Permissions on the application key govern what the addon can do. A 403 from the endpoint usually isn't the addon's fault; it's the app key lacking user write permission. The error surfaces as a generic Laravel authorization failure, so check the key's scopes before you dive into the addon code.

Debug from the panel, not from your client. Tail storage/logs/laravel.log on the panel while you fire a request. Because the addon runs inside the panel's Laravel app, Log::debug() calls you add in its controller (or an Event::listen you register) give you full request context that the HTTP response hides.

Config quirks: there usually aren't any. Packages this size often hardcode the route prefix and permission checks rather than exposing config. Don't assume a config/pterodactyl-api-addon.php exists — check src/ and the service provider's register()/boot() methods. If you need different behavior, the extension point is overriding the addon's controller via a route in your own service provider, or forking.

Extension points worth knowing. Pterodactyl's event system fires on API key creation if the addon uses the panel's models properly — listen for it to mirror tokens into your own audit table. For anything the addon doesn't do (expiry, key rotation, per-key permissions), you'll be writing it yourself; the package is a thin route + controller layer, not a full token lifecycle manager.