La API, para automatizar tu cuenta

Qué consigues: leer y cambiar cosas de tu cuenta desde tus propios programas: bajarte las facturas a tu contabilidad, abrir tickets desde tu sistema de incidencias, consultar el estado de tus servicios.

Dos formas de entrar, y no sirven para lo mismo

Con qué	Para qué parte	Cuánto dura
Clave de API	Tus sitios: webs, dominios, DNS, correo, bases de datos, FTP y certificados.	No caduca hasta que tú la revocas.
Usuario y contraseña (testigo JWT)	Facturas, tickets, avisos y tu perfil.	60 minutos, y hay que renovarlo.

Si lo que quieres es automatizar tus sitios —una copia de seguridad nocturna, un paso de tu pipeline, un script que crea el sitio de cada cliente nuevo— lo que necesitas es la clave de API. Es lo que empieza aquí abajo.

Important

Para la parte de sitios, el testigo JWT no funciona. No es que esté desaconsejado: devuelve un error de permisos. Usa la clave.

Crear tu clave

En el panel, en Cuenta ‣ Claves para IA. La clave se enseña una sola vez: cópiala en ese momento y guárdala donde guardes tus contraseñas. Si la pierdes, no se recupera — se revoca y se crea otra.

nxp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Qué puede hacer tu clave

Una clave recién creada sólo lee. Los permisos van por separado porque los riesgos son distintos:

Permiso	Qué abre	Cómo se consigue
`sitios:leer`	Consultar (`GET`)	Al crear la clave
`sitios:escribir`	Crear y cambiar (`POST`, `PUT`, `PATCH`)	Pídelo en un ticket
`sitios:borrar`	Borrar (`DELETE`)	Pídelo en un ticket

Borrar no va dentro de escribir a propósito: crear un sitio de más se arregla borrándolo; borrar el que no era, no.

Si a tu clave le falta el permiso, la respuesta te dice cuál falta. No tienes que adivinarlo probando.

Usarla

Una cabecera, en cada petición:

Authorization: Bearer nxp_tu_clave

O X-API-Key: nxp_tu_clave si tu herramienta no te deja tocar Authorization.

Un ejemplo entero, listar tus sitios:

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

Y crear uno:

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

Si prefieres no escribir curl, hay una herramienta de línea de órdenes que hace lo mismo en una línea.

La lista completa de operaciones

Está en https://my.hostbrid.com/api/docs/, y se lee sin cuenta. Cada operación dice el permiso que necesita.

Sólo ves lo tuyo

Todo va acotado a tu cuenta. Pedir por identificador algo de otro cliente devuelve 404, no 403: un 403 confirmaría que ese identificador existe.

Límites

Cada clave tiene su propio límite de peticiones por minuto. Al pasarte, la respuesta es un 429: espera y reintenta. El contador de la API va aparte del de la tienda, así que automatizar copias de seguridad no te deja sin buscador de dominios en la web.

Si crees que la clave se ha filtrado

Revócala en el panel, en la misma pantalla donde la creaste. Deja de valer al instante. Después crea otra: no hay forma de «cambiarle la contraseña» a una clave, y es a propósito.

Facturas, tickets y perfil: eso sigue con usuario y contraseña

Esa parte todavía no acepta la clave. Se pide un testigo:

POST /api/v1/auth/token/

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

y responde access (60 minutos, el que se usa en cada petición) y refresh (7 días, el que sirve para pedir otro, en /api/v1/auth/token/refresh/).

Si tienes la verificación en dos pasos activada, hay que mandar además el código de seis dígitos en el campo otp, y sólo al pedir el testigo, no en cada petición.

Important

El testigo de renovación cambia cada vez que lo usas: la respuesta trae uno nuevo y el anterior deja de valer. Guarda siempre el último.

Por eso esta parte no sirve para procesos desatendidos: renovar necesita tu contraseña, y con verificación en dos pasos, un código que un programa no puede teclear. Estamos trabajando en que la clave valga también aquí. Si es lo que necesitas, dínoslo en un ticket: sirve para priorizarlo.

Qué hay en la parte de usuario y contraseña

Filtrado a tu cuenta, como todo: sólo ves lo tuyo.

Para qué	Dónde
Resumen de tu cuenta — contadores de todos los módulos de una vez	`GET /api/v1/dashboard/stats/`
Facturas — listarlas y leerlas, con número, base, impuestos, total y líneas de detalle	`GET /billing/api/invoices/`
Suscripciones — qué planes tienes y hasta cuándo	`GET /billing/api/subscriptions/`
Pagos — el histórico	`GET /billing/api/payments/`
Datos de facturación — tus datos fiscales	`/billing/api/profiles/`
Consumo — los registros de uso que se facturan	`GET /billing/api/usage/`
Tickets — abrirlos, leerlos y responder	`/tickets/api/tickets/`
Avisos — las notificaciones del panel	`/notifications/api/v1/notifications/`
Tus claves SSH	`/accounts/api/ssh-keys/`
Tu perfil	`/accounts/api/`

Las facturas son de sólo lectura a propósito: las emite el sistema, y una factura emitida no se borra ni se inventa desde fuera.

Ejemplo con el testigo: bajarse las facturas

En tres pasos:

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

Las listas vienen paginadas de 20 en 20. La respuesta trae el enlace a la página siguiente; sigue ese enlace hasta que no haya más.

Lo que puedes hacer depende de tu rol

Dentro de una organización hay tres roles, y la API los respeta igual que el panel:

Administrador y miembro — pueden leer y cambiar.
Sólo lectura — pueden leer, y cualquier intento de crear o borrar responde que no tienes permisos suficientes.

Si una petición de escritura te devuelve un error de permisos y crees que no debería, mira primero qué rol tienes en la organización.

Lo que todavía no está listo

Qué	Estado
La clave para facturas, tickets y perfil	Hoy la clave sólo abre la parte de sitios. Esa otra sigue con usuario y contraseña. En curso.
Despliegue desde git (Projects) y su CLI	En desarrollo. La herramienta de línea de órdenes que ya existe (La terminal: hostbrid) es para el hosting, no para esto.
Avisos automáticos hacia tus sistemas (webhooks)	No disponibles para clientes todavía.

Problemas frecuentes

Con la clave, todo me responde que no estoy autenticado: Comprueba que la cabecera dice Bearer, un espacio, y la clave entera empezando por nxp_. Si sigue, mira en el panel que no la hayas revocado.
Con la clave, los sitios me dan error de permisos y el resto también: Estás usando la clave contra facturas o tickets: ahí todavía no vale. Esa parte va con usuario y contraseña.
Con el testigo, todo me responde que no estoy autenticado: Casi siempre es que pasaron los 60 minutos. Renueva el testigo. Y si lo estás usando contra /api/sites/v1/, ahí no funciona: usa la clave.
El refresco me dice que el testigo no vale: Estás reusando uno ya gastado. Cada renovación devuelve uno nuevo: guarda siempre el último. Si lo has perdido, vuelve a pedir el par con usuario y contraseña.
Pido el testigo y me lo rechaza aunque la contraseña es buena: Tienes la verificación en dos pasos activada y falta el campo otp.
Me responde que no tengo permisos: O tu rol es de sólo lectura, o estás pidiendo algo de otra organización.

Si te falta algo, dilo

Esta parte está creciendo. Si necesitas un dato o una operación que no está en la tabla, ábrenos un ticket contando qué quieres automatizar. Es la mejor forma de que aparezca aquí.