HF PanelDocsv1.0.0

Create an API token and automate account creation

Make a Read & change API token limited to your script's IP, then create, list, suspend and delete hosting accounts with curl.

This tutorial makes an API token and uses it from a script to create a hosting account, look it up and suspend it, the same things a billing system does. The examples use curl; any language that can send HTTPS requests works.

You need: an administrator or reseller login, and a computer or server to run the script from. A reseller's token only sees that reseller's customers and follows their privileges.

1. Find the API address

The API answers at https://api.yourdomain.com:2087/v1. Check it from your script's computer:

bash
curl -s https://api.yourdomain.com:2087/v1

The answer lists the endpoints. If the server has no api. address, use https://panel.yourdomain.com:8443/api/v1 instead. See API overview.

2. Make the token

  1. Open your username at the top right › Password & security, and find API tokens.
  2. In Name, type what it is for, for example Signup script.
  3. Choose Read & change in Access.
  4. In Allowed IPs, enter the public IP address of the computer that runs the script, for example 203.0.113.5.
  5. Type your password (or a code from your authenticator app) and click Create token.
  6. Click Copy token and keep it in your script's secret settings. It is shown only once.

Important: a Read & change token can create and delete accounts. Always limit it with Allowed IPs, and never put it in a website's public code.

3. Set up your shell

bash
A=https://api.yourdomain.com:2087/v1
H="Authorization: Bearer hf_xxx"
curl -s -H "$H" $A/me

/me answers with the login the token belongs to.

4. Look at the packages

bash
curl -s -H "$H" $A/packages

Note the name or id of the package new accounts should get, for example Starter.

5. Create an account

bash
curl -s -H "$H" -H 'Content-Type: application/json' $A/accounts \
     -d '{"username":"sarahbakes","email":"sarah@example.com","package":"Starter","domain":"example.com","welcome":true}'

The answer (status 201) holds the new account and its password. With "welcome": true the customer also gets the welcome email. Check warning: it is null unless something besides the account failed, such as adding the domain.

Common refusals come back as status 422 with a plain error, for example That username is taken. or No such package: Gold.

6. List and read accounts

bash
curl -s -H "$H" $A/accounts
curl -s -H "$H" $A/accounts/sarahbakes

7. Suspend, unsuspend and delete

bash
curl -s -H "$H" -X POST $A/accounts/sarahbakes/suspend
curl -s -H "$H" -X POST $A/accounts/sarahbakes/unsuspend
curl -s -H "$H" -X DELETE $A/accounts/sarahbakes

Suspending stops the account's websites, email and logins; unsuspending switches them back on. Deleting removes the account with all its websites, email and databases, and can't be undone. Changing the package or password is in API: accounts.

Note: when deleting accounts needs another administrator's approval, DELETE /v1/accounts/{username} answers 403 and the delete must be done in the panel.

8. Handle errors

Status What to do
401 the token is missing or wrong: send Authorization: Bearer hf_…
403 a read-only token, an IP not in Allowed IPs, or a missing privilege
422 read error and fix the field it names
429 too many failed attempts from your IP: fix the token and wait 15 minutes

9. Get told when things happen (optional)

HF Panel can send alerts, such as a website going down or a backup failing, to your own address as signed webhooks. Add a webhook channel on the Notifications screen: see Webhooks.