IONOS Cloud API token: the DCD is not the Control Center, how long it lasts and how to make it read-only

This site's IONOS Cloud guide explains in four steps how to generate the token in the DCD and paste it. Search Console showed me people arrive with questions the guide does not answer: "ionos controlcenter", "dcd ionos", "ionos api token". I gathered them here: where each IONOS credential is created, how long the token lasts, how to build a user that really can only read, and how to revoke it. Everything comes from IONOS documentation: docs.ionos.com, the Auth API reference and the ionosctl reference.

DCD, Control Center and Developer Portal: three places, two credentials

• The DCD (Data Center Designer, dcd.ionos.com) is the IONOS Cloud console: virtual data centers, servers, LANs, IP blocks. The Cloud API token is generated there, under Menu → Management → Token Manager.
• The customer panel at my.ionos.com, the one many people search for as "IONOS Control Center", is where products are ordered. The Cloud API token is not created in that panel: the Token Manager lives in the DCD.
• The hosting Developer Portal (developer.hosting.ionos.com) issues something else: API keys with a public prefix and a secret, sent in the X-API-Key header, after you enable API access to hosting services from my.ionos.com. According to its own documentation, those APIs configure hosting products (domains, DNS, SSL). If you wanted a token for your DCD servers, that key is not it.

The Cloud API (https://api.ionos.com/cloudapi/v6) accepts the token as Authorization: Bearer, or a username and password over Basic. The token is the option that expires on its own and can be revoked without changing anyone's password.

Three ways to generate the token, and how long it lasts

From the DCD: Menu → Management → Token Manager → Generate Token. The TTL comes from a list (1 hour, 4 hours, 1, 7, 30, 60, 90, 180 or 365 days), and the token value is shown only once; you can download it as a text file at that moment. The list keeps the ID, the creation date and the expiration date, never the value.

Through the API or ionosctl, the TTL is given in seconds (or as 30D in the CLI), with a minimum of 60 seconds and a maximum of one year, which is also the default if you do not ask for one:

# Auth API: a 30-day token (2,592,000 s) with username and password
curl -s -u "$IONOS_USERNAME:$IONOS_PASSWORD" \
  "https://api.ionos.com/auth/v1/tokens/generate?ttl=2592000"

# the same with ionosctl
ionosctl token generate --ttl 30D

# which tokens the user has and when each one expires
ionosctl token list

Two limits stated in the Auth API reference. Basic authentication on that endpoint only works if the user has no 2FA; with 2FA, the token is generated in the DCD Token Manager. And there is a cap of 100 active tokens per user, which a script that generates a new one on every run reaches quickly. ionosctl token delete --expired clears the expired ones.

For an integration that only reads, I pick 90 days and write down the expiration date: that day the integration stops reading, and I would rather it happen with a heads-up. One year is the API default, not a recommendation.

Read-only: the token has no scopes, the user has limits

The token carries no permissions of its own: it acts with the identity of the user who generated it. The contract owner and administrators can see and modify everything (the Users & Groups page notes that administrators have access to every resource in the contract without being in any group), so a token generated from your administrator user is an administrator token, whatever you use it for. A read token comes from a user who is not an administrator: least privilege built with IONOS RBAC, which the same page describes as users, groups, privileges and shared resources. In the DCD, Menu → Management → Users & Groups:

• Users → Create: a new user, with an email and password, not promoted to administrator.
• Groups → Create: a group, and on the Privileges tab you tick nothing. Privileges are contract-wide actions (create data centers, reserve IP blocks, create snapshots or Kubernetes clusters); a read group needs none of them.
• Members: add the user to the group.
• Resources of Group → Grant Access: every data center and IP block it should see. According to the documentation, assigning the resource enables read access; Edit and Share are separate checkboxes that stay unticked.
• Log in to the DCD as that user and generate the token in its Token Manager. That is the token that goes into any inventory tool.

With ionosctl it is the same. The share create reference says a share grants read/use access by default; editing is the --edit-privilege flag:

# a group with no privileges, with the user in it
ionosctl compute group create --name "read-only"
ionosctl compute group user add --group-id "$GROUP_ID" --user-id "$USER_ID"

# IDs of the resources that can be shared
ionosctl compute resource list

# one share per data center, without --edit-privilege or --share-privilege
ionosctl compute share create --group-id "$GROUP_ID" --resource-id "$DATACENTER_ID"

Before pasting it anywhere, check what it is. ionosctl token parse shows the token ID, the user, the contract and the role, and with --privileges that user's privileges. The Cloud API tells you which data centers it sees:

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

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

If the list comes back empty, the token is fine: the documentation warns that resources created by the contract owner are not visible to other users until they are shared with their group. The Grant Access for that data center is missing.

Metrics are a separate case. The ionosctl reference describes the "access and manage monitoring" privilege as access to metrics and alarm management. If you want to see the servers' CPU and network with that user, it is the only privilege I would add, knowing that with it the user is no longer purely read-only.

Revoking: Token Manager, API and the 2FA detail

In the Token Manager, Delete invalidates the token immediately, even if it has not expired. Through the API and the CLI you delete by ID (DELETE /auth/v1/tokens/{tokenId}) or by criteria: CURRENT (the one you are using), EXPIRED or ALL.

ionosctl token list # ID, creation and expiration
ionosctl token delete --token-id "$TOKEN_ID"
ionosctl token delete --expired
ionosctl token delete --current # the one in IONOS_TOKEN

With 2FA enabled, the Auth API reference says deletion can only be done from the Token Manager. And there is another way to cut access without touching the token: remove the data center from the group (Revoke Access in Resources of Group). The token stays alive, but it stops seeing that resource.

What Control Cloud does with that token

The Control Cloud form offers a token or a username and password, but each organization's inventory and metrics are read with the token, so that is what to paste. It is stored encrypted and used against Cloud API v6 to list data centers, servers, LANs and IP blocks and draw them on the map, and against the Telemetry API for a server's metrics when you open its panel. With the read-only user above the map works; starting or stopping servers from Control Cloud needs Edit on that data center. One detail that came from real use: the code detects a token pasted twice in a row and keeps one. The step-by-step to connect it is in the IONOS Cloud guide; if you want to try it with your contract, request access.