Primeros pasos con la API

Claves de API y autenticación

Cada petición lleva una clave de API de organización como token Bearer en la cabecera Authorization. Las claves se crean en la consola y pueden limitarse a tus redes.

Envía la clave como token Bearer en la cabecera Authorization de cada petición. La clave pertenece a una organización y la API obtiene la organización de la propia clave, por lo que no hace falta ninguna otra cabecera para indicar a qué organización corresponde una petición; una cabecera X-ORGANIZATION-ID enviada junto a ella se ignora.

curl --request GET \
  --url https://api.serverside.com/v1/baremetal \
  --header 'Authorization: Bearer <api-key>'

La API también lee la clave desde una cabecera X-API-KEY, un alias para la misma credencial. Una petición solo lleva una credencial: X-API-KEY junto con una cabecera Authorization, o cualquiera de ellas enviada dos veces, se rechaza con 400 (Errores de autenticación).

Crear una clave

La primera clave se obtiene en la consola en la nube: en los ajustes de tu organización, Manage API Keys tiene un botón Create an API Key. Solicita un nombre y, opcionalmente, las redes desde las que funcionará la clave. La clave creada se muestra una vez y no puede volver a mostrarse, así que guárdala inmediatamente en un gestor de secretos o una variable de entorno.

Una clave tiene 63 caracteres: org_ seguido de 59 caracteres de base64 seguro para URL, que pueden incluir - y _. Solo un valor Bearer que empiece por org_ se interpreta como clave de API. Cualquier otro valor se trata como token de sesión de la consola, por lo que una clave pegada sin su prefijo falla con 401.

Las claves se gestionan solo en la consola. Los endpoints que crean, enumeran y modifican claves requieren una sesión de consola iniciada, así que una clave no puede crear, enumerar ni modificar otra.

Operaciones que una clave no puede invocar

La referencia de la API enumera todas las operaciones que una clave puede invocar. El resto de la API sirve a la consola: los ajustes de la organización, miembros, invitaciones, roles, claves de API, notificaciones, tu perfil de usuario, tickets de soporte y listas de países y divisas. Cada una de estas operaciones responde a una clave con 401 y este cuerpo:

{
  "success": false,
  "data": null,
  "code": "UNAUTHENTICATED",
  "message": "This endpoint requires a signed-in user session. Organization API keys are not accepted here.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B"
}

Permisos de las claves

Una clave nueva recibe todos los permisos que tiene el rol Admin integrado el día de su creación; por eso la consola etiqueta cada clave como Full Permissions. El conjunto nunca se actualiza después. Un permiso añadido posteriormente a la plataforma falta en las claves creadas antes y un endpoint que lo compruebe responde a esas claves con 403; una clave creada después del cambio sí lo tiene.

Cada página de endpoint de la referencia indica el permiso que comprueba la operación, por ejemplo organization.baremetal.deploy en Desplegar sistema operativo. Siete operaciones no comprueban ninguno y cualquier clave de la organización puede invocarlas: las listas y consultas de planes bare metal y de bloques de IP, Listar regiones, Obtener derechos y Listar claves SSH. Todas las demás comprueban uno de estos:

Permiso	Operaciones
`organization.baremetal.read`	Todas las lecturas de un servidor: detalles, estado y alimentación, operaciones, lecturas de hardware, ancho de banda, actividad, puertos de red, redes virtuales e imágenes y aplicaciones que puede instalar
`organization.baremetal.update`	Cambiar el nombre de un servidor, su modo de arranque y leer o cambiar su script iPXE
`organization.baremetal.deploy`	Desplegar un sistema operativo, ejecutar pruebas de hardware y cancelar cualquiera de ellos
`organization.baremetal.power`	Comandos de alimentación y reinicios del BMC
`organization.baremetal.console`	Sesiones de consola y medios virtuales
`organization.baremetal.networking`	Crear y eliminar segmentos de un servidor y conectarlo a redes virtuales o desconectarlo de ellas
`organization.baremetal.lock`	Bloquear y desbloquear un servidor
`organization.networking.read`	Leer redes virtuales, bloques de IP y sus direcciones, disponibilidad de VLAN y resultados de análisis de seguridad, y encolar un nuevo análisis
`organization.networking.virtual.manage`	Crear, renombrar y eliminar redes virtuales
`organization.networking.addresses.manage`	Asignar, reservar y liberar direcciones y DNS inverso
`organization.billing.read`	Pedidos, facturas y sus PDF, suscripciones, uso y crédito de cuenta
`organization.billing.pay`	Pagar facturas, comprar crédito y gestionar tarjetas guardadas
`organization.billing.orders.create`	Pedidos y servidores y bloques de IP creados con facturación por hora
`organization.billing.subscriptions.manage`	Cancelar suscripciones y eliminar servidores y bloques de IP
`organization.assets.iso.read`	Enumerar imágenes ISO en la biblioteca y en un servidor
`organization.assets.iso.manage`	Subir y eliminar imágenes ISO
`organization.sshkeys.manage`	Añadir, renombrar y eliminar claves SSH
`organization.activity.read`	Registro de actividad de la organización

No se pueden crear claves con menos permisos que el rol Admin, así que una clave nueva los tiene todos.

Limitar una clave a tus redes

Una clave sin redes permitidas funciona desde cualquier dirección. En cuanto tiene al menos una, una petición desde fuera de todas ellas se rechaza como si la clave fuera incorrecta. Una entrada es una dirección individual (198.51.100.7) o una red en formato CIDR (198.51.100.0/24), IPv4 o IPv6, definida en la consola; una clave nueva admite hasta 100.

La API compara las redes con la dirección que Cloudflare comunica para la conexión. Si una clave restringida recibe un 401 en el probador de peticiones, ejecuta la misma petición con cURL desde un equipo permitido.

Desactivar una clave

Desactivar una clave en la consola la detiene sin perder sus ajustes; eliminarla la borra definitivamente. Una clave desactivada, eliminada o caducada falla en todas las peticiones igual que una incorrecta. La caducidad es independiente del interruptor de activación, así que activar una clave caducada no hace que vuelva a funcionar.

Errores de autenticación

Estado	`code`	Cuándo
`400`	`VALIDATION_ERROR`	La petición envía `X-API-KEY` junto con una cabecera `Authorization`, o una de las dos dos veces. El único detalle `INVALID_VALUE` identifica esa cabecera en `field`, con `location` `header`.
`401`	`UNAUTHENTICATED`	Falta la cabecera; la clave es incorrecta, está desactivada, caducada o eliminada; o la petición procede de fuera de sus redes permitidas. El `message` es "Authentication is required or the supplied credentials are invalid."
`401`	`UNAUTHENTICATED`	La operación requiere una sesión de consola (Operaciones que una clave no puede invocar). El `message` lo indica.
`403`	`NO_PERMISSION`	La clave es válida, pero le falta el permiso indicado por el endpoint.

Una clave enviada de ambas formas obtiene esta respuesta:

{
  "success": false,
  "data": null,
  "code": "VALIDATION_ERROR",
  "message": "X-API-KEY: Send one credential: the API key in the Authorization header or in X-API-KEY, not both.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B",
  "details": [
    {
      "code": "INVALID_VALUE",
      "message": "Send one credential: the API key in the Authorization header or in X-API-KEY, not both.",
      "field": "X-API-KEY",
      "location": "header"
    }
  ]
}

Ambas respuestas 401 llevan cabeceras WWW-Authenticate que indican las credenciales aceptadas por el endpoint: Bearer y ApiKey header="X-API-KEY" donde funciona una clave, solo Bearer en una operación exclusiva de consola, donde representa el token de sesión de la consola.

El primer 401 no indica cuál de sus causas se ha dado. Comprueba la propia clave y que aparezca tras Bearer , después su estado en Manage API Keys de la consola y después sus redes permitidas, en ese orden.