Table of Contents
Authentication
Authentication with the API requires that an API Key and API Secret Key be generated in the panel, and proper permissions be assigned. Once you have done that, making requests to the API is simple.
You will need to send the Authorization header with a Bearer included in order for requests to be accepted. The API key itself is sent in the following form: <api key>.<hmac-sha256 [url][body]>.
Parts
<api key> — this is your public API key that is used to identify the request.
. — this period is simply a delimitation in the Bearer and is required.
<hmac-sha256 [url][body]> — this is a HMAC-SHA-256 hash of the full request URL (including parameters, not url encoded), and the raw request body connected together with no spaces between them.
Example HMAC (PHP)
$apiPublic = '5rETe3i9PPQUWlT7';
$apiSecret = 'FlahSJvWRo33B3LI.GF1yrd9Vqgreayd';
$url = 'https://pterodactyl.local/api/users';
$body = '';
$hmac = hash_hmac('sha256', $url . $body, $apiSecret, true);
return $apiPublic . '.' . base64_encode($hmac);
The code above will output 5rETe3i9PPQUWlT7.G/d0/1RQiKMnCPQjzvOBbcBhKsykucvCiNXKsvXA7Ec=.
Sending Header
We would then take that generated token and send it with an Authorization header on our request.
Authorization: Bearer 5rETe3i9PPQUWlT7.G/d0/1RQiKMnCPQjzvOBbcBhKsykucvCiNXKsvXA7Ec=
Errors
HTTP/400 — occurs when the HMAC hash is not valid for the request. This is often due to a mistake in the hashing method on the sender's end, however, you should use caution to confirm that it was not due to a potential Man-in-the-Middle attack.
HTTP/401 — occurs when the authentication header is missing or malformed.
HTTP/403 — occurs if the request IP is not approved for the API key used or the API key does not have permission for the requested resource.