Token de API de IONOS Cloud: el DCD no es el Control Center, cuánto dura y cómo hacerlo de solo lectura

La guía de IONOS Cloud de este sitio explica en cuatro pasos cómo generar el token en el DCD y pegarlo. Search Console me mostró que la gente llega con preguntas que la guía no contesta: "ionos controlcenter", "dcd ionos", "ionos api token". Las junté acá: dónde se crea cada credencial de IONOS, cuánto dura el token, cómo se arma un usuario que de verdad sólo puede leer y cómo se revoca. Todo sale de la documentación de IONOS: docs.ionos.com, la referencia de la Auth API y la de ionosctl.

DCD, Control Center y Developer Portal: tres lugares, dos credenciales

• El DCD (Data Center Designer, dcd.ionos.com) es la consola de IONOS Cloud: data centers virtuales, servidores, LANs, IP blocks. El token de la Cloud API se genera ahí, en Menu → Management → Token Manager.
• El panel de cliente de my.ionos.com, el que muchos buscan como "IONOS Control Center", es donde se contratan los productos. El token de la Cloud API no se crea en ese panel: el Token Manager vive en el DCD.
• El Developer Portal de hosting (developer.hosting.ionos.com) emite otra cosa: API keys con un public prefix y un secret, que se mandan en el header X-API-Key, después de activar el acceso a la API de hosting desde my.ionos.com. Según su propia documentación, esas APIs configuran productos de hosting (dominios, DNS, SSL). Si buscabas un token para los servidores del DCD, esa key no es.

La Cloud API (https://api.ionos.com/cloudapi/v6) acepta el token como Authorization: Bearer o usuario y contraseña por Basic. El token es la opción que vence sola y se revoca sin cambiar la contraseña de nadie.

Tres formas de generar el token, y cuánto dura

Desde el DCD: Menu → Management → Token Manager → Generate Token. El TTL se elige de una lista (1 hora, 4 horas, 1, 7, 30, 60, 90, 180 o 365 días), y el valor del token se muestra una sola vez; en ese momento se puede descargar como archivo de texto. En la lista quedan el ID, la fecha de creación y la de vencimiento, nunca el valor.

Por API o con ionosctl, el TTL va en segundos (o como 30D en la CLI), con un mínimo de 60 segundos y un máximo de un año, que también es el valor por defecto si no lo pedís:

# Auth API: un token de 30 días (2.592.000 s) con usuario y contraseña
curl -s -u "$IONOS_USERNAME:$IONOS_PASSWORD" \
  "https://api.ionos.com/auth/v1/tokens/generate?ttl=2592000"

# lo mismo con ionosctl
ionosctl token generate --ttl 30D

# qué tokens tiene el usuario y cuándo vence cada uno
ionosctl token list

Dos límites que figuran en la referencia de la Auth API. La autenticación Basic de ese endpoint sólo funciona si el usuario no tiene 2FA; con 2FA, el token se genera en el Token Manager del DCD. Y hay un tope de 100 tokens activos por usuario, que un script que genera uno nuevo en cada corrida alcanza rápido. ionosctl token delete --expired limpia los vencidos.

Para una integración que sólo lee, yo elijo 90 días y anoto la fecha de vencimiento: ese día la integración deja de leer, y prefiero que pase con aviso. Un año es el valor por defecto de la API, no una recomendación.

Solo lectura: el token no tiene scopes, el usuario sí tiene límites

El token no lleva permisos propios: actúa con la identidad del usuario que lo generó. El dueño del contrato y los administradores ven y pueden modificar todo (la página Users & Groups aclara que los administradores tienen acceso a todos los recursos del contrato sin estar en ningún grupo), así que un token generado desde tu usuario administrador es un token de administrador, lo uses para lo que lo uses. Un token de lectura sale de un usuario que no es administrador: mínimo privilegio armado con el RBAC de IONOS, que la misma página describe como usuarios, grupos, privilegios y recursos compartidos. En el DCD, Menu → Management → Users & Groups:

• Users → Create: un usuario nuevo, con su email y contraseña, sin promoverlo a administrador.
• Groups → Create: un grupo, y en la pestaña Privileges no marcás nada. Los privilegios son acciones sobre el contrato (crear data centers, reservar IP blocks, crear snapshots o clusters de Kubernetes); un grupo de lectura no necesita ninguno.
• Members: sumás el usuario al grupo.
• Resources of Group → Grant Access: cada data center y cada IP block que tiene que ver. Según la documentación, asignar el recurso habilita la lectura; Edit y Share son casillas aparte, que quedan sin marcar.
• Entrás al DCD con ese usuario y generás el token en su Token Manager. Ese es el token que va en cualquier herramienta de inventario.

Con ionosctl se arma igual. La referencia de share create dice que el share, por defecto, da acceso de lectura y uso; editar es el flag --edit-privilege:

# grupo sin privilegios, con el usuario adentro
ionosctl compute group create --name "solo-lectura"
ionosctl compute group user add --group-id "$GROUP_ID" --user-id "$USER_ID"

# IDs de los recursos que se pueden compartir
ionosctl compute resource list

# un share por data center, sin --edit-privilege ni --share-privilege
ionosctl compute share create --group-id "$GROUP_ID" --resource-id "$DATACENTER_ID"

Antes de pegarlo en ningún lado, comprobá qué es. ionosctl token parse muestra el ID del token, el usuario, el contrato y el rol, y con --privileges los privilegios de ese usuario. La Cloud API dice qué data centers ve:

ionosctl token parse --token "$IONOS_TOKEN"
ionosctl token parse --token "$IONOS_TOKEN" --privileges

# data centers visibles para este token
curl -s -H "Authorization: Bearer $IONOS_TOKEN" \
  "https://api.ionos.com/cloudapi/v6/datacenters?depth=1" | jq -r '.items[].properties.name'

Si la lista sale vacía, el token está bien: la documentación avisa que los recursos que creó el dueño del contrato no son visibles para otros usuarios hasta que se comparten con su grupo. Falta el Grant Access de ese data center.

Las métricas son un caso aparte. La referencia de ionosctl describe el privilegio "access and manage monitoring" como acceso a métricas y gestión de alarmas. Si querés ver CPU y red de los servidores con ese usuario, es el único privilegio que le sumaría, sabiendo que con él deja de ser lectura pura.

Revocar: Token Manager, API y el detalle de 2FA

En el Token Manager, Delete invalida el token en el momento, aunque no haya vencido. Por API y CLI se borra por ID (DELETE /auth/v1/tokens/{tokenId}) o por criterio: CURRENT (el que estás usando), EXPIRED o ALL.

ionosctl token list # ID, creación y vencimiento
ionosctl token delete --token-id "$TOKEN_ID"
ionosctl token delete --expired
ionosctl token delete --current # el de IONOS_TOKEN

Con 2FA activado, la referencia de la Auth API dice que el borrado sólo se puede hacer desde el Token Manager. Y hay otra forma de cortar el acceso sin tocar el token: sacar el data center del grupo (Revoke Access en Resources of Group). El token sigue vivo, pero deja de ver ese recurso.

Lo que hace Control Cloud con ese token

El formulario de Control Cloud ofrece token o usuario y contraseña, pero el inventario y las métricas de cada organización se leen con el token, así que es lo que conviene pegar. Lo guarda cifrado y lo usa contra la Cloud API v6 para listar data centers, servidores, LANs e IP blocks y dibujarlos en el mapa, y contra la Telemetry API para las métricas de un servidor cuando abrís su panel. Con el usuario de solo lectura de arriba el mapa funciona; prender o apagar servidores desde Control Cloud necesita Edit sobre ese data center. Un detalle que salió del uso: el código detecta un token pegado dos veces seguidas y se queda con uno. El paso a paso para conectarlo está en la guía de IONOS Cloud; si querés probarlo con tu contrato, pedí acceso.