Primera petició a l’API de Hostbrid: clau, permisos i cURL

L’API REST permet connectar un script o una aplicació amb els serveis del teu compte Hostbrid. Abans d’automatitzar canvis, fes una petició de lectura, comprova que veus els recursos esperats i entén quin permís necessita cada operació. La referència pública es genera a partir de les rutes actives del tauler: fes-la servir com a font de veritat quan canviïn els endpoints.

1. Crea i desa una clau

Obre Configuració → claus d’API i crea una clau. El valor complet només es mostra una vegada. Desa’l en un gestor de secrets o en el mecanisme segur del teu entorn; no el pugis a Git, no l’incloguis en JavaScript del navegador ni l’enganxis en un prompt o una captura. Si algú el veu, revoca’l i crea’n un altre.

Una clau nova permet consultar. Els permisos per escriure, operar màquines o esborrar són independents; alguns s’han de demanar a suport. Concedeix només el permís que necessita la tasca. La clau continua activa fins que la revoques; no caduca al cap de poca estona.

2. Fes una petició de lectura

Defineix HOSTBRID_API_KEY a l’entorn protegit del terminal i consulta els teus llocs amb una petició GET:

curl --fail-with-body \
  -H "Authorization: Bearer $HOSTBRID_API_KEY" \
  https://my.hostbrid.com/api/sites/v1/sites/

La clau comença per nxp_. Si l’eina no permet configurar Authorization, pots enviar la mateixa clau a X-API-Key. No utilitzis el token de sessió del tauler ni un JWT: l’API de client s’autentica amb la clau llarga.

Aquest exemple només consulta. Abans de crear o modificar un recurs, revisa el mètode, el cos esperat i el permís a la referència OpenAPI. La consola mostra l’esquema, però no executa peticions des del navegador. Cada clau té el seu propi límit de peticions; evita consultar en bucle si no hi ha canvis.

3. Llegeix el resultat abans de continuar

Tracta la resposta com a dades del teu compte. Comprova l’estat HTTP i el JSON abans de donar la tasca per acabada. Un 200 no demostra per si sol que s’hagi desat el canvi que volies; una resposta de lectura només confirma aquella consulta.

Resposta	Què cal revisar
`401`	Falta la clau, està mal copiada, s’ha revocat o la capçalera té un format incorrecte.
`403`	La clau no té el permís requerit. Revisa l’abast que indica la referència; no provis mètodes a l’atzar.
`404`	La ruta o el recurs no existeix per al teu compte. No es revelen recursos d’altres comptes.
`429`	Has superat el límit per clau. Redueix la freqüència i evita repeticions innecessàries.

No repeteixis a cegues un POST que pugui crear una comanda o un recurs: comprova primer si l’operació anterior s’ha completat. No desis capçalera d’autenticació als registres ni comparteixis captures que la continguin.

Després de la primera petició

Per consultar tot el catàleg, els permisos per operació i els esquemes de petició, obre la referència de l’API REST. Si prefereixes executar tasques des del terminal, llegeix la guia de la CLI. Per connectar un assistent compatible amb MCP, consulta API, CLI i MCP per automatitzar Hostbrid i la guia per connectar una IA.

Si automatitzes la contractació i el cicle de vida del maquinari, segueix la guia de l’API per a servidors dedicats.

Aquesta guia no activa permisos, compra cap servei ni demostra que un script qualsevol sigui segur. Comença amb lectures i concedeix permisos d’escriptura només quan necessitis una acció concreta.