Connect your Pterodactyl game server to Discord safely, with a restricted subuser API key

Before you start

• Have an online Build Discord Bots bot with the Pro Game Server module enabled, plus access to an existing Pterodactyl server. Free publishes 1 bot and 10 custom commands; Pro publishes 3 bots and 200 custom commands.
• Use the server owner or an authorized panel user who can create subusers. Arrange a separate panel account and email address for this integration, with no administrator role, owned servers or access to other servers.
• Use your panel’s public HTTPS address, its server’s short identifier and a Client API key belonging to the dedicated user. A panel Application API key is not the credential this module expects. Panel themes and hosts can change menu labels or restrict API-key creation.

1. Match the module’s calls to the permissions you need

   All REST server calls use /api/client/servers/{identifier}. GET on that path reads server details, allocations and the user_permissions metadata. GET /resources reads power state and resource usage for status and !serverstats. These reads require access to that server; stock Pterodactyl does not define a separate control.read or resources.read subuser permission.

   GET /websocket obtains short-lived credentials for a connection to Wings. websocket.connect permits console output and live statistics. Stock Pterodactyl adds this permission automatically when saving a subuser and hides it from the permission editor; a customized panel may expose it. Wings receives auth, send stats and, depending on the enabled feature, send logs. The module renews the WebSocket credentials through GET /websocket.

   control.console permits Wings send command messages. The module sends list to obtain supported Minecraft player data, and enabled chat-relay or whitelist features also send console commands. Optional Discord console input sends user-entered commands only when its settings and role checks allow it. This integration does not use REST POST /command for those features.

   control.restart permits the existing confirmed !restart command, which uses REST POST /power with signal restart. The optional live-panel buttons send Wings set state with start, stop or restart: add control.start, control.stop and control.restart if you enable all three buttons. The module never needs file, backup, database, schedule, startup, allocation-management or subuser-management permissions for these calls.

   Pterodactyl: documented subuser permission reference · Pterodactyl: Client API route reference · Pterodactyl: server-read authorization · Pterodactyl: automatic websocket.connect permission

2. Invite a dedicated subuser on one server

   Sign in to the panel as the owner, open the intended server, then open Users and Create new subuser. Enter the dedicated account’s email. If it is new to the panel, complete the account setup through your host’s invitation process. Pterodactyl can create a non-admin account for a new email, or reuse an existing account. Verify that the reused account has no other server access.

   For the live integration and its Test connection check, select Control → Console (control.console). websocket.connect should already be added by stock Pterodactyl; verify it in the connection result. Leave other permission categories unchecked. Add only control.restart if you intentionally want !restart. Add all three power permissions only when you intend to enable the live-panel power buttons.

   For REST status and !serverstats alone, server membership is sufficient and you can omit control.console and all power permissions. Leave live features off in that case. The current Test connection checker still requires websocket.connect and control.console even with Power buttons off, so a deliberately REST-only setup can report missing control.console. Do not grant console access just to turn that check green if you only need REST reads.

   Pterodactyl: subuser editor and permission selection · Pterodactyl: account creation and one-server assignment

3. Create a Client API key as the dedicated user

   Sign out of the owner account, then sign in as the dedicated subuser. Confirm the panel shows only the intended server. In Account → API Credentials (normally /account/api), create a key with a descriptive name such as Discord game status. Copy the full newly displayed Client API key, which starts with ptlc_. Do not create it under the owner or panel administrator account.

   Pterodactyl’s standard Client key form takes a description and optional Allowed IPs, not a per-server permission selection. The restriction comes from the account’s server assignments and subuser permissions. If you use Allowed IPs, obtain the actual bot-host egress address from your hosting provider; your phone or home IP is not the address making the bot’s API requests. Keep the key private and paste it only into the module settings.

   Pterodactyl: API Credentials account route · Pterodactyl: Client API key form and Allowed IPs

4. Save the key in Game Server settings

   In your bot’s Modules tab, enable Game Server and open its Settings. Select the intended Discord server before editing. Under Pterodactyl Panel, set Panel URL to your own public HTTPS panel address. Enter the dedicated user’s key in Client API Key. For the field labeled Server UUID, use the short identifier from the panel’s /server/abcdefgh URL, not a numeric admin database ID. Use your actual identifier instead of the example.

   For a Pterodactyl-only REST setup, choose Generic / Pterodactyl only as Game Type. Save the settings before Test connection: that check reads saved credentials, not unsaved input. The dashboard shows a saved-key indicator and last four characters rather than returning the full key. Leaving the key field blank keeps the existing saved key; use Remove key and save if you want to remove it.

   If you want the live panel, configure its status channel and enable Live panel. Keep Power buttons, Allow console commands and optional chat features off until you intentionally configure their permissions and roles. If mirroring console output, use a private staff channel. Console output can contain operational and player information; masking selected IDs does not make every line safe for public viewing.

5. Check the connection and its limits

   After saving, press Test connection. It reads server details, GET /websocket and GET /resources, then reports server information, WebSocket credential availability and missing permissions. With Power buttons off it checks websocket.connect and control.console; with them on it also checks control.start, control.stop and control.restart. The check does not execute a power action or console command, and obtaining WebSocket credentials is not proof of a successful live Wings session.

   For an unauthorized result, check whether the Client key is still active. For forbidden or not found, check the dedicated account’s server membership and the short identifier. For missing permissions, edit only that server’s subuser entry, save and test again. A live connection additionally needs the bot host to reach the panel-supplied Wings WebSocket address. Test !serverstats in a staff channel; test power controls only when a server interruption is acceptable.

   Panel resource APIs do not provide player counts. The current live integration parses supported Minecraft Bedrock console output and list replies for player data; it cannot guarantee a count for arbitrary games. REST running state describes the server process, not proof that players can join. Keep unknown player data unknown rather than presenting it as zero.

   To retire the connection, turn off its live features and remove the saved key. Revoke the key in the dedicated user’s API Credentials and remove its server subuser assignment if no longer needed. Removing the key from Build Discord Bots alone does not revoke it in Pterodactyl. If the key leaks, revoke it in the panel and create a replacement with the same narrow account access.