The API, for automating your account

What you get: read and change things in your account from your own programs: pull your invoices into your accounting, open tickets from your incident system, check the status of your services.

Two ways in, and they are not for the same job

With what	For which part	How long it lasts
API key	Your sites: websites, domains, DNS, email, databases, FTP and certificates.	It does not expire until you revoke it.
User and password (JWT token)	Invoices, tickets, alerts and your profile.	60 minutes, and it has to be renewed.

If what you want is to automate your sites — a nightly backup, a step in your pipeline, a script that creates the site for every new customer — what you need is the API key. That is what starts just below.

Important

For the sites part, the JWT token does not work. It is not that it is discouraged: it returns a permissions error. Use the key.

Create your key

In the panel, under Account ‣ AI keys. The key is shown only once: copy it right then and store it wherever you keep your passwords. If you lose it, it cannot be recovered — you revoke it and create another one.

nxp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

What your key can do

A newly created key can only read. Permissions are separate because the risks are different:

Permission	What it opens	How to get it
`sitios:leer`	Read (`GET`)	When you create the key
`sitios:escribir`	Create and change (`POST`, `PUT`, `PATCH`)	Ask for it in a ticket
`sitios:borrar`	Delete (`DELETE`)	Ask for it in a ticket

Delete is deliberately not part of write: creating one site too many is fixed by deleting it; deleting the wrong one is not.

If your key is missing the permission, the reply tells you which one. You do not have to guess by trial and error.

Using it

One header, on every request:

Authorization: Bearer nxp_tu_clave

Or X-API-Key: nxp_tu_clave if your tool will not let you touch Authorization.

A full example, listing your sites:

curl -H "Authorization: Bearer $HOSTBRID_TOKEN" \
     https://my.hostbrid.com/api/sites/v1/sites/

And creating one:

curl -X POST \
     -H "Authorization: Bearer $HOSTBRID_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"domain": "ejemplo.com", "php_version": "8.3"}' \
     https://my.hostbrid.com/api/sites/v1/sites/

Tip

If you would rather not write curl, there is a command-line tool that does the same in one line.

The full list of operations

It is at https://my.hostbrid.com/api/docs/, and it can be read without an account. Each operation states the permission it needs.

You only see what is yours

Everything is scoped to your account. Asking by identifier for something belonging to another customer returns 404, not 403: a 403 would confirm that identifier exists.

Limits

Each key has its own requests-per-minute limit. When you go over it, the reply is a 429: wait and retry. The API counter is separate from the store one, so automating backups will not leave you without the domain search on the site.

If you think the key has leaked

Revoke it in the panel, on the same screen where you created it. It stops working instantly. Then create another one: there is no way to “change the password” of a key, and that is on purpose.

Invoices, tickets and profile: those still use user and password

That part does not accept the key yet. You request a token:

POST /api/v1/auth/token/

{ "username": "tu-usuario", "password": "tu-contraseña" }

and it replies with access (60 minutes, the one used on every request) and refresh (7 days, the one used to ask for another, at /api/v1/auth/token/refresh/).

If you have two-step verification on, you also have to send the six-digit code in the otp field, and only when asking for the token, not on every request.

Important

The refresh token changes every time you use it: the reply brings a new one and the previous one stops working. Always keep the latest one.

That is why this part is no good for unattended processes: renewing needs your password, and with two-step verification, a code that a program cannot type. We are working on making the key valid here too. If that is what you need, tell us in a ticket: it helps us prioritize it.

What is in the user-and-password part

Scoped to your account, like everything else: you only see what is yours.

What for	Where
Summary of your account — counters for every module at once	`GET /api/v1/dashboard/stats/`
Invoices — list and read them, with number, net, taxes, total and detail lines	`GET /billing/api/invoices/`
Subscriptions — which plans you have and until when	`GET /billing/api/subscriptions/`
Payments — the history	`GET /billing/api/payments/`
Billing details — your tax details	`/billing/api/profiles/`
Usage — the usage records that get billed	`GET /billing/api/usage/`
Tickets — open them, read them and reply	`/tickets/api/tickets/`
Alerts — the panel notifications	`/notifications/api/v1/notifications/`
Your SSH keys	`/accounts/api/ssh-keys/`
Your profile	`/accounts/api/`

Invoices are read only on purpose: the system issues them, and an issued invoice is not deleted or invented from outside.

Token example: downloading your invoices

In three steps:

1. POST /api/v1/auth/token/
   { "username": "…", "password": "…" }
   → guarda "access" y "refresh"

2. GET /billing/api/invoices/
   Authorization: Bearer <access>
   → la primera página de facturas

3. GET /billing/api/invoices/?page=2
   Authorization: Bearer <access>
   → las siguientes

Lists come paginated 20 at a time. The reply carries the link to the next page; follow that link until there are no more.

What you can do depends on your role

Inside an organization there are three roles, and the API honors them just like the panel:

Administrator and member — can read and change.
Read only — can read, and any attempt to create or delete replies that you do not have enough permissions.

If a write request returns a permissions error and you think it should not, first check which role you have in the organization.

What is not ready yet

What	Status
The key for invoices, tickets and profile	Today the key only opens the sites part. That other part still uses user and password. In progress.
Deployment from git (Projects) and its CLI	In development. The command-line tool that already exists (The command line: hostbrid) is for hosting, not for this.
Automatic alerts to your systems (webhooks)	Not available to customers yet.

Common problems

With the key, everything replies that I am not authenticated: Check that the header says Bearer, a space, and the whole key starting with nxp_. If it carries on, check in the panel that you have not revoked it.
With the key, sites give me a permissions error and so does everything else: You are using the key against invoices or tickets: it is not valid there yet. That part goes with user and password.
With the token, everything replies that I am not authenticated: Almost always the 60 minutes are up. Renew the token. And if you are using it against /api/sites/v1/, it does not work there: use the key.
The refresh tells me the token is not valid: You are reusing one that has already been spent. Every renewal returns a new one: always keep the latest. If you have lost it, ask for the pair again with user and password.
I ask for the token and it is rejected even though the password is right: You have two-step verification on and the otp field is missing.
It replies that I do not have permissions: Either your role is read only, or you are asking for something from another organization.

If something is missing, tell us

This part is growing. If you need a piece of data or an operation that is not in the table, open a ticket telling us what you want to automate. It is the best way for it to show up here.