Token de API da IONOS Cloud: o DCD não é o Control Center, quanto tempo dura e como deixá-lo somente leitura

O guia da IONOS Cloud deste site explica em quatro passos como gerar o token no DCD e colá-lo. O Search Console me mostrou que as pessoas chegam com perguntas que o guia não responde: "ionos controlcenter", "dcd ionos", "ionos api token". Juntei aqui: onde cada credencial da IONOS é criada, quanto o token dura, como montar um usuário que de fato só pode ler e como revogá-lo. Tudo sai da documentação da IONOS: docs.ionos.com, a referência da Auth API e a do ionosctl.

DCD, Control Center e Developer Portal: três lugares, duas credenciais

• O DCD (Data Center Designer, dcd.ionos.com) é o console da IONOS Cloud: data centers virtuais, servidores, LANs, IP blocks. O token da Cloud API é gerado ali, em Menu → Management → Token Manager.
• O painel de cliente do my.ionos.com, o que muita gente procura como "IONOS Control Center", é onde os produtos são contratados. O token da Cloud API não é criado nesse painel: o Token Manager fica no DCD.
• O Developer Portal de hospedagem (developer.hosting.ionos.com) emite outra coisa: API keys com um public prefix e um secret, enviadas no header X-API-Key, depois de ativar o acesso à API de hospedagem pelo my.ionos.com. Segundo a própria documentação, essas APIs configuram produtos de hospedagem (domínios, DNS, SSL). Se você procurava um token para os servidores do DCD, essa key não é.

A Cloud API (https://api.ionos.com/cloudapi/v6) aceita o token como Authorization: Bearer, ou usuário e senha por Basic. O token é a opção que vence sozinha e pode ser revogada sem trocar a senha de ninguém.

Três formas de gerar o token, e quanto ele dura

Pelo DCD: Menu → Management → Token Manager → Generate Token. O TTL é escolhido de uma lista (1 hora, 4 horas, 1, 7, 30, 60, 90, 180 ou 365 dias), e o valor do token aparece uma única vez; nesse momento dá para baixá-lo como arquivo de texto. Na lista ficam o ID, a data de criação e a de vencimento, nunca o valor.

Pela API ou com o ionosctl, o TTL vai em segundos (ou como 30D na CLI), com mínimo de 60 segundos e máximo de um ano, que também é o padrão se você não pedir outro:

# Auth API: um token de 30 dias (2.592.000 s) com usuário e senha
curl -s -u "$IONOS_USERNAME:$IONOS_PASSWORD" \
  "https://api.ionos.com/auth/v1/tokens/generate?ttl=2592000"

# o mesmo com o ionosctl
ionosctl token generate --ttl 30D

# quais tokens o usuário tem e quando cada um vence
ionosctl token list

Dois limites que constam na referência da Auth API. A autenticação Basic desse endpoint só funciona se o usuário não tiver 2FA; com 2FA, o token é gerado no Token Manager do DCD. E há um teto de 100 tokens ativos por usuário, que um script que gera um novo a cada execução alcança rápido. ionosctl token delete --expired limpa os vencidos.

Para uma integração que só lê, eu escolho 90 dias e anoto a data de vencimento: nesse dia a integração para de ler, e prefiro que isso aconteça com aviso. Um ano é o padrão da API, não uma recomendação.

Somente leitura: o token não tem escopos, o usuário tem limites

O token não carrega permissões próprias: ele age com a identidade do usuário que o gerou. O dono do contrato e os administradores veem e podem modificar tudo (a página Users & Groups esclarece que administradores têm acesso a todos os recursos do contrato sem estar em nenhum grupo), então um token gerado pelo seu usuário administrador é um token de administrador, seja qual for o uso. Um token de leitura sai de um usuário que não é administrador: mínimo privilégio montado com o RBAC da IONOS, que a mesma página descreve como usuários, grupos, privilégios e recursos compartilhados. No DCD, Menu → Management → Users & Groups:

• Users → Create: um usuário novo, com e-mail e senha, sem promovê-lo a administrador.
• Groups → Create: um grupo, e na aba Privileges você não marca nada. Privilégios são ações sobre o contrato (criar data centers, reservar IP blocks, criar snapshots ou clusters de Kubernetes); um grupo de leitura não precisa de nenhum.
• Members: adicione o usuário ao grupo.
• Resources of Group → Grant Access: cada data center e cada IP block que ele deve ver. Segundo a documentação, atribuir o recurso habilita a leitura; Edit e Share são caixas à parte, que ficam desmarcadas.
• Entre no DCD com esse usuário e gere o token no Token Manager dele. Esse é o token que vai em qualquer ferramenta de inventário.

Com o ionosctl é igual. A referência do share create diz que o share, por padrão, dá acesso de leitura e uso; editar é a flag --edit-privilege:

# grupo sem privilégios, com o usuário dentro
ionosctl compute group create --name "somente-leitura"
ionosctl compute group user add --group-id "$GROUP_ID" --user-id "$USER_ID"

# IDs dos recursos que podem ser compartilhados
ionosctl compute resource list

# um share por data center, sem --edit-privilege nem --share-privilege
ionosctl compute share create --group-id "$GROUP_ID" --resource-id "$DATACENTER_ID"

Antes de colá-lo em qualquer lugar, confira o que ele é. ionosctl token parse mostra o ID do token, o usuário, o contrato e o papel, e com --privileges os privilégios desse usuário. A Cloud API diz quais data centers ele vê:

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

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

Se a lista vier vazia, o token está certo: a documentação avisa que os recursos criados pelo dono do contrato não ficam visíveis para outros usuários até serem compartilhados com o grupo deles. Falta o Grant Access desse data center.

As métricas são um caso à parte. A referência do ionosctl descreve o privilégio "access and manage monitoring" como acesso a métricas e gestão de alarmes. Se você quer ver CPU e rede dos servidores com esse usuário, é o único privilégio que eu acrescentaria, sabendo que com ele o usuário deixa de ser somente leitura.

Revogar: Token Manager, API e o detalhe do 2FA

No Token Manager, Delete invalida o token na hora, mesmo que não tenha vencido. Pela API e pela CLI se apaga por ID (DELETE /auth/v1/tokens/{tokenId}) ou por critério: CURRENT (o que você está usando), EXPIRED ou ALL.

ionosctl token list # ID, criação e vencimento
ionosctl token delete --token-id "$TOKEN_ID"
ionosctl token delete --expired
ionosctl token delete --current # o de IONOS_TOKEN

Com 2FA ativado, a referência da Auth API diz que a exclusão só pode ser feita pelo Token Manager. E há outra forma de cortar o acesso sem mexer no token: tirar o data center do grupo (Revoke Access em Resources of Group). O token continua vivo, mas deixa de ver esse recurso.

O que o Control Cloud faz com esse token

O formulário do Control Cloud oferece token ou usuário e senha, mas o inventário e as métricas de cada organização são lidos com o token, então é ele que convém colar. Ele fica guardado cifrado e é usado contra a Cloud API v6 para listar data centers, servidores, LANs e IP blocks e desenhá-los no mapa, e contra a Telemetry API para as métricas de um servidor quando você abre o painel dele. Com o usuário somente leitura acima o mapa funciona; ligar ou desligar servidores pelo Control Cloud precisa de Edit nesse data center. Um detalhe que saiu do uso: o código detecta um token colado duas vezes seguidas e fica com um. O passo a passo para conectar está no guia da IONOS Cloud; se quiser testar com o seu contrato, peça acesso.