Essentials API
Essentials API gives your Pelican panel an HTTP API at /api/essentials/v1 for a Discord bot or a script of your own: who is playing, which servers have no backup, how full each node is, what the shop took and what the ticket desk is waiting on. Keys are asked for, granted, narrowed, replaced and revoked from the panel. It is a reading API: nothing here starts, stops or reaches into a server. For that, use Pelican's own client API at /api/client.
At a glance
| Plugin ID | essentials-api |
| Current version | 1.1.7 |
| Pelican Panel | 1.0 (tested on 1.0.0-rc.2) |
| Needs | Three database tables (created at install). Pelican's frontend build for its stylesheet (Node.js and Yarn on the panel server). HTTPS on the panel is strongly advised. |
| Works with (optional) | Essentials Core, Essentials Monitoring, Essentials Support, Essentials Shop, Essentials Game Manager (each answers part of the API), the Essentials website |
| Adds | Admin area, sidebar group Essentials API, page API. Client area page API access (in the user menu, in the client area and inside servers). A tab Essentials API on the account profile page. The API itself under /api/essentials/v1. |
| Permissions | Role editor section Essentials API: View, Update, Api, View Api |
Before you install
- Decide what you need it for. Half of what the API can answer comes from other Essentials plugins; without them those addresses answer 404 (see "What it answers").
- Make sure the older all-in-one Essentials plugin (plugin id
essentials) is not running on this panel. See "Things to watch out for". - Pelican Panel 1.0 (tested on 1.0.0-rc.2), which needs PHP 8.4 or 8.5.
- The panel's database user must be allowed to create and alter tables. The install creates three tables.
- Node.js and Yarn on the panel server. The plugin ships a stylesheet that Pelican builds into the panel's frontend when the plugin is installed.
- The queue worker (Pelican's background worker, usually the systemd service
pelican-queue), because installs started from the admin area run there. - The panel should be reached over HTTPS. Every API call carries its key in a request header.
Command examples in this guide assume Pelican is installed in /var/www/pelican and the web server user is www-data (Debian/Ubuntu). On another setup, adapt the path and the user (for example nginx on some systems).
Check the queue worker with:
systemctl status pelican-queue
The API has no timed work of its own, so it does not need the scheduler.
Installing
Download the plugin from the Essentials website, https://essentialsplugins.nl: sign in, open the catalogue, pick Essentials API and a version, and download the zip. x.y.z is a stable release, x.y.z-beta a test release and x.y.z-dev a development build. Use a stable release on a live panel.
Pick one of these routes. The first is the easiest.
-
From the admin area. Go to Admin -> Plugins -> Import from File and choose the zip. The plugin appears in the list; press Install. Pelican says "Plugin install started in the background". Refresh after a minute until the plugin shows Enabled. (Pelican also has Import from URL.)
-
From the Essentials website. Connect your panel on the website with a Pelican application key (made on the panel under Admin -> API keys, with read and write on Plugins; it starts with
papp_). Then press Install on the plugin's page on the website. -
With Essentials Auto Updater. Its Plugin updates page offers Essentials modules that are not installed yet.
-
Command line (advanced). Unzip so the folder is exactly
/var/www/pelican/plugins/essentials-api, then:sudo chown -R www-data:www-data /var/www/pelican/plugins/essentials-api cd /var/www/pelican sudo -u www-data php artisan p:plugin:install essentials-api sudo -u www-data php artisan p:plugin:listThe list must say the plugin is enabled. Unzipping over an existing plugin folder resets it to "not installed", so always run the install command again after unzipping.
What the install does:
- It creates (or upgrades) three tables:
essentials_api_keys(the keys, stored as hashes),essentials_connections(Discord accounts tied to panel accounts) andessentials_api_writes(a short record that stops a retried write from happening twice). This happens at every install and update. - Coming from the all-in-one Essentials plugin, those three tables already exist and are used as they are: existing keys keep working at the same addresses, permissions are taken over once, and settings follow what the all-in-one had until you save them here.
- It clears Pelican's route and view caches and asks the queue worker to restart.
After every install or update:
-
If the API page answers 404 or an old version still shows, reload PHP-FPM and restart the worker:
sudo systemctl reload php8.4-fpm sudo systemctl restart pelican-queueUse your own PHP version in the service name.
-
Run artisan, yarn and file commands as the web user (
sudo -u www-data ...), never as root. Files created by root cause errors and failed updates later. -
If the API pages look unstyled, rebuild the frontend:
cd /var/www/pelican && sudo -u www-data yarn build. With Essentials Core installed, the Panel health section on the Essentials page reports missing built assets.
First-time setup
- Give your admin roles access: Admin -> Roles, section Essentials API. Root Admins already have everything.
- Api (or Update): grant, refuse, replace and revoke keys, make new keys, and change the settings.
- View Api (or View): see the list of keys without deciding anything.
- Asking for a key of your own needs no permission.
- Open Admin -> Essentials API -> API. In How this works:
- API: whether the API answers at all. Off registers no address at all.
- Requests wait to be granted: on by default. On, a person who asks for a key gets one when somebody with permission grants it. Off, they get one straight away.
- Requests a minute, per key: default 60.
- A granted key lasts: in days. 0 means until revoked (the default).
- Remove the panel own API keys tab: optional. Takes Pelican's own API keys tab off the account profile page, so only one thing there is called API keys. Pelican's client API can still make account keys for anything that asks it directly, and existing Pelican keys keep working.
- Press Save.
Keys for people
A personal key answers only for the servers its owner can already open, checked the same way the panel checks it.
- The person opens the user menu (under their name) -> API access and presses Ask for a key. They fill in What is it for and, optionally, Anything worth adding. (The Essentials API tab on their profile page has a Create button that does the same.)
- With Requests wait to be granted on, an admin opens Admin -> Essentials API -> API and presses Grant or Refuse. A refusal can carry a message under What to tell them, shown on the person's own page.
- The person goes back to API access and presses Show my key. The key is shown once. It is stored as a hash, so nobody, including the panel's administrators, can read it back later.
Keys for a bot
- On Admin -> Essentials API -> API, press New key.
- Fill in What is it for and Whose it is (who is answerable for the key; for a personal key it is also what the key can see). Pick yourself for a bot's key: a key in somebody else's name is not shown to you, that person collects it once under API access (from 1.1.7 on). A whole-panel key can only belong to somebody with the Api (or Update) permission, and it stops working the moment they lose it.
- Under Reaches, pick Their own servers or The whole panel. Only a whole-panel key can ask the panel-wide questions.
- Under What it may ask about, untick everything the bot does not need. Every reading is ticked to begin with; Answer and close tickets and Tie Discord accounts to panel accounts are not, so tick those only for a bot that has to answer tickets or connect accounts.
- Optionally set Requests a minute for this key. Empty follows the panel setting; 0 means no limit at all.
- The key is granted at once and shown once. Copy it to the bot's configuration straight away.
What a key may ask about
| Ability | What it covers |
|---|---|
| Prove the key works | /health only. Safe to call on a timer. |
| Its own servers | The owner's servers, their backups and the services they pay for. |
| The whole panel | Every node, every backup, stopped schedules, the watchdog and the panel host. Needs a whole-panel key. |
| What the shop took | Shop figures: this month and the last, what is owed and overdue, running services. Needs a whole-panel key. |
| Ask a server directly | Who is playing and whether a server is running. These reach a game server or the daemon, so answers are cached for fifteen to twenty seconds. |
| The ticket desk | Tickets, answers and which are waiting. Staff notes are never included. Needs a whole-panel key. |
| Answer and close tickets | The only ability that changes something a customer sees: it replies to and closes tickets as staff. |
| Tie Discord accounts to panel accounts | Connects Discord accounts to panel accounts and creates Pelican API keys on those accounts. Needs a whole-panel key. |
Keys asked for by people, and keys from before abilities existed, may use everything their scope allows except Answer and close tickets. A narrowed key may only do what is ticked, including abilities added in later releases. Abilities cannot be changed on an existing key: make a new one and revoke the old one.
Calling the API
Send the key in the Authorization header and nothing else. A key in the address is refused.
curl -H "Authorization: Bearer esk_xxxxxxxxxxxx_yyyyyyyy..." https://panel.example.com/api/essentials/v1/health
Keys look like esk_<prefix>_<secret>. The prefix is public and is what the Key column shows, so you can tell keys apart without seeing the secret. Every answer includes rate.limit and rate.remaining.
Both API pages carry the full reference under How to use this API: every address, what to send, what comes back and an example, with Download as Markdown and Download as OpenAPI.
What it answers
| Addresses | Answered by |
|---|---|
/health, /servers/{server}/status, the /connect family |
this plugin and Pelican |
/nodes, /system, /capacity, /backups, /schedules, /alerts, /me/servers, /me/backups, /connect/{discord}/backups |
Essentials Monitoring (404 without it) |
/tickets, /tickets/{ticket}, /tickets/{ticket}/messages, /tickets/{ticket}/close |
Essentials Support (404 without it) |
/shop, /me/services, /connect/{discord}/services |
Essentials Shop (answers selling: false without it) |
/servers/{server}/players |
Essentials Game Manager (404 without it) |
A 404 caused by a missing plugin, or by that part being switched off in its plugin, names the part in its body ("part": ...).
Discord connections (optional)
On API access, a person can press Connect Discord. They get a code to send in Discord within ten minutes, in a channel your bot reads. This needs a Discord bot of your own that uses the API with a key holding Tie Discord accounts to panel accounts; no bot comes with this plugin. Connecting creates a Pelican API key called "Discord (Essentials)" on the person's account. The Disconnected button on the same page ends the connection and deletes that key.
Connecting a panel to the Essentials website
The Essentials website can store an Essentials API key for your panel, next to a Pelican application key (papp_). It uses the Essentials API key for one thing: reading which Pelican version the panel runs, so it can check that a plugin version fits before offering it. Listing, installing and updating plugins from the website use the Pelican application key, never this one. Without an Essentials API key the website still connects with the application key alone, but offers versions without checking that they fit your panel.
For the version check to work:
- Install Essentials Monitoring as well. The Pelican version comes from
/system, which Monitoring answers. - On Admin -> Essentials API -> API, press New key, choose The whole panel under Reaches, and keep Prove the key works and The whole panel ticked. You can untick everything else.
- Paste the key into the panel connection on the website.
A personal key from API access connects, but cannot answer the panel-wide /system question, so the version stays unknown. The website only connects to panels on an https:// address.
Things to watch out for
- Uninstalling deletes every key. Pelican rolls the plugin's migration back on uninstall, which drops all three tables: keys, Discord connections and the write log. From 1.1.7 on it first deletes the Pelican API keys that Connect Discord made on people's accounts. That is deliberate (a key that outlives the thing that answers it is a credential nobody can revoke), but it means every bot stops and every person needs a new key after a reinstall.
- Treat keys like passwords. A key is shown once. Keep it in the bot's configuration or a secret store, never in a public repository, a chat message or an address. If one leaks, Revoke it at once and make a new one.
- Check the boxes before you create a key. Every reading starts ticked, so untick what the bot does not need. The two boxes that change something (Answer and close tickets and Tie Discord accounts to panel accounts) start unticked from 1.1.6 on; in 1.1.5 and older they started ticked too.
- A rate of 0 means no limit. Reasonable for a bot on your own machine; risky for a key that leaves it.
- Expiring keys. With A granted key lasts set, keys stop on their expiry date with no warning in the panel. A bot can read its key's expiry from
/health. - Replacing an active key from the admin page (Replace) makes a new key with the same reach, abilities and limits. The old one keeps working for another week (never longer than its own expiry) and then stops. The new key waits on its owner's API access page to be collected with Show my key, even for a bot key owned by an admin.
- Approval off means instant keys. With Requests wait to be granted off, anybody signed in gets a personal key the moment they ask. It only sees their own servers, but choose this deliberately.
- Switching the API off removes the addresses completely. Bots then get 404, not 401.
- Roles saved while the plugin is off lose its permissions. Pelican only keeps the permission sections it draws, and a switched-off plugin draws none. Switch the plugin on before editing roles.
- Do not run it next to the all-in-one Essentials plugin. "Essentials" (plugin id
essentials) is the older plugin that contains what the modules now do separately. Installing a module switches the all-in-one off; installing the all-in-one on a panel with modules can switch modules off; and uninstalling the all-in-one deletes database tables the modules share, including the API keys. Pick one: the all-in-one, or the modules. An all-in-one release too old to hand the API over makes this plugin refuse to start, with a message saying so.
Things to keep an eye on
- The key list. On the API page, check Last used and Expires now and then. Revoke keys nobody uses, and keys of people who left. Remove clears revoked and refused rows from the list.
- Waiting requests. With approval on, requests sit in the list as Waiting until somebody answers them.
- Health notes. With Essentials Core, the Essentials page shows "The API is on, but its keys table is missing. Reinstall Essentials API." when the table is gone, and "The API is on, but no key has been granted yet, so nothing can call it." when no key is active.
- Too many 429 answers. If a bot keeps hitting the limit, give its key its own Requests a minute for this key or make the bot ask less often.
- Logs. Errors go to
storage/logs/laravel-YYYY-MM-DD.log(orlaravel.log). Pelican's log viewer reads the whole file, so very large logs (around 100 MB) make it fail; Essentials Core warns above 50 MB. - Backups. The keys live in the database; include it in your backups, together with
storage/app/private/essentials.
Updating
- Make a database backup first. This plugin keeps its keys and Discord connections in tables.
- Download the new version and import it the same way (Pelican shows Update on the plugin when an update is known), or let Essentials Auto Updater do it.
- The tables are checked and upgraded during every update. Keys keep working, settings are kept, and the plugin switches itself back on after an update through the admin area.
- The
v1in the address is a promise about the shape of the answers: fields and addresses may be added, but insidev1none changes meaning, changes type or goes away. Theapifield in every answer tells a bot which version of the plugin answered.
Removing it
Uninstalling through Admin -> Plugins deletes:
- the tables
essentials_api_keys,essentials_connectionsandessentials_api_writes. Every key stops working and every Discord connection is gone.
It does not delete:
- the settings file
storage/app/private/essentials/api/settings.jsonand small marker files in the same folder; - Pelican API keys that Discord connections created on people's accounts (named "Discord (Essentials)"). Those are Pelican's own keys; people can remove them on the API keys tab of their account.
To remove the leftovers:
sudo rm -r /var/www/pelican/storage/app/private/essentials/api
If you only want the API to stop answering without losing keys, switch API off on the API page, or disable the plugin, instead of uninstalling it.
Troubleshooting
| Problem | What to do |
|---|---|
401 with "error": "unauthorized" |
The key is wrong, revoked, expired, not yet collected, or its owner was deleted. Check that the header is exactly Authorization: Bearer <key>. A granted key only works after its owner pressed Show my key. |
403 with "ability": ... |
The key was not granted that ability. Make a new key with it ticked and revoke the old one. |
403 with "needs": "panel" |
That question needs a whole-panel key. Only an admin can make one, with New key. |
404 with "part": ... |
The plugin that answers this address is not installed, or that part is switched off in it. See "What it answers". |
404 on every address, without a part |
API is switched off, the plugin is disabled, or a cached route list predates the install. Run cd /var/www/pelican && sudo -u www-data php artisan optimize:clear. |
429 with "error": "too_many_requests" |
The key used up its requests for this minute. Wait, slow the bot down, or raise the key's own limit. |
| The API admin page is missing | The keys table does not exist yet (or the role lacks View Api, Api, View or Update). Reinstall the plugin so the install creates the tables. |
| A person's key shows Active but they never saw it | Granting does not show the key to the admin. The person must press Show my key on their own API access page. |
| Somebody lost their key | Keys cannot be read back. On API access, Replace stops the old key and asks for a new one (it waits for approval if that is on). An admin can use Replace on the API page as well. |
| The plugin will not start: "Update legacy Essentials to a version supporting standalone API, or disable legacy Essentials before enabling this plugin" | An older all-in-one Essentials plugin is enabled. Switch it off under Admin -> Plugins. Do not uninstall it without reading "Things to watch out for": that deletes the API keys table. |
| The Essentials website cannot read the Pelican version | Use a whole-panel key with Prove the key works and The whole panel ticked, and install Essentials Monitoring. |
Essentials is a community project by Legend Development. Not affiliated with or endorsed by the Pelican team.