Skip to content

Accessing the Cleura Cloud REST API

Cleura Cloud provides a REST API, which you can take advantage of with a tool like curl. But before you do, you must create a token for the current session. For that, you only need to have an account in Cleura Cloud.

Creating a token

Cleura Cloud REST API calls use token authentication. The process of obtaining a valid token works slightly differently, based on whether your account has two-factor authentication (2FA) enabled or not.

If you do not have 2FA enabled for your account, to create a token, have your username (your_cc_username) and password (your_cc_password) to the Cleura Cloud handy and type:

curl -d '{"auth": {"login": "your_cc_username", "password": "your_cc_password"}}' \
    https://rest.cleura.cloud/auth/v1/tokens

Provided you typed your username and password correctly and that there were no connection issues to the remote endpoint, you will get a JSON object with a string (token) that holds your session token:

{
  "result": "login_ok",
  "token": "vahkie7EiDaij7chegaitee2zohsh1oh"
}

If your Cleura Cloud account has 2FA enabled, you must configure it with SMS as a second-factor option. Accounts with only WebAuthn as their second factor cannot be used for Cleura Cloud REST API operations.

First, initiate a token request giving your Cleura Cloud username and password, and setting the twofa_method option to sms:

curl -d '{"auth": {"login": "your_cc_username", "password": "your_cc_password", "twofa_method": "sms"}}' \
    https://rest.cleura.cloud/auth/v1/tokens

Instead of a token, you will get a verification code (look at verification):

{
  "result": "twofactor_required",
  "type": "sms",
  "verification": "ahb4en3cho"
}

This verification code is required for requesting a 2FA code:

curl -d '{"request2fa": {"login": "your_cc_username", "verification": "ahb4en3cho"}}' \
    https://rest.cleura.cloud/auth/v1/tokens/request2facode

You will now receive your 6-digit second-factor code via an SMS message. This enables you to request your REST API token like this:

curl -d '{"verify2fa": {"login": "your_cc_username", "verification": "ahb4en3cho", "code": 123456}}' \
    https://rest.cleura.cloud/auth/v1/tokens/verify2fa

Make sure not to put the code in quotes, for it is of type integer and that fact should be reflected during the assignment to code. You will get a JSON object with your token:

{
  "result": "login_ok",
  "token": "fiushood9oraTiNa4ban3eemeezoeDae"
}

Now that you have obtained a valid token, you can proceed with making Cleura Cloud REST API calls.

Testing the token

One way to make sure the token is valid is by getting a list of all supported regions. All you have to do is use curl to provide your username (your_cc_username) and token and connect to the https://rest.cleura.cloud/accesscontrol/v1/openstack/domains endpoint:

curl -H "X-AUTH-LOGIN: your_cc_username" \
    -H "X-AUTH-TOKEN: vahkie7EiDaij7chegaitee2zohsh1oh" \
    https://rest.cleura.cloud/accesscontrol/v1/openstack/domains

All supported regions should be returned as objects in a JSON array:

[
  {
    "area": {
      "id": "6",
      "name": "Sweden \/ Stockholm",
      "tag": "SE_STO2",
      "regions": [
        {
          "zone_id": "2",
          "name": "Stockholm \/ Sweden",
          "status": "active",
          "region": "Sto2"
        }
      ]
    },
    "id": "b7c3998142f0496aa3582d8a3ae9ae1e",
    "status": "provisioned",
    "name": "CCP_Domain_123P456",
    "enabled": true
  },
  {
    "area": {
      "id": "7",
      "name": "Germany \/ Frankfurt",
      "tag": "DE",
      "regions": [
        {
          "zone_id": "6",
          "name": "Frankfurt \/ Germany",
          "status": "active",
          "region": "Fra1"
        }
      ]
    },
    "id": "2d04a791db0e4a799b65c3794eda09bf",
    "status": "provisioned",
    "name": "CCP_Domain_123P456",
    "enabled": true
  },
  {
    "area": {
      "id": "1",
      "name": "Europe",
      "tag": "EU",
      "regions": [
        {
          "zone_id": "1",
          "name": "Karlskrona \/ Sweden",
          "status": "active",
          "region": "Kna1"
        }
      ]
    },
    "id": "989d137c832c42eb9a6c6839a5c28675",
    "status": "provisioned",
    "name": "CCP_Domain_123P456",
    "enabled": true
  }
]

Using the cleura CLI

Rather than crafting every Cleura Cloud REST API call with a tool like curl and manually managing your session token, you can use the cleura CLI.

cleura is a command-line client for the Cleura Cloud REST API It obtains and stores a token on your behalf, and covers functionality such as account users, OpenStack identity resources (domains, projects, users, and role assignments), and Gardener Kubernetes clusters.

Warning

cleura CLI is in early (0.x) development. Even though it is functional and has been tested against live Cleura Cloud environments, its command coverage is still limited, and its commands and flags may change between releases.

Installing the cleura CLI

Use whichever method suits your environment.

The install script downloads the latest release binary, verifies its checksum, and installs it into /usr/local/bin, using sudo if necessary:

curl -fsSL https://raw.githubusercontent.com/cleura/cleura-cli/main/install.sh | sh

Set BINDIR to install into another directory, like $HOME/.local/bin. Set CLEURA_VERSION to install a specific release, like v0.7.1.

brew install cleura/tap/cleura

At first launch, macOS may block cleura. If that happens, go to the Privacy & Security section of System Settings and allow the execution of cleura.

Provided you have Go 1.25 or later available, type:

go install github.com/cleura/cleura-cli/cmd/cleura@latest

Download the archive that matches your operating system and architecture from the releases page. Extract the archive and place the resulting cleura binary somewhere on your PATH. Every release comes with a checksums.txt file, signed with cosign, which allows you to verify the authenticity of what you have downloaded.

Logging in and testing access

Instead of creating a token yourself, you let cleura obtain and store one on your behalf:

cleura login

This command prompts you for your Cleura Cloud username and password. Just like the Cleura Cloud REST API itself, cleura supports SMS as the only second factor for accounts with two-factor authentication (2FA) enabled.

Should your account rely on WebAuthn or a passkey instead, create an API token on the Cleura Cloud Management Panel, and store it like this:

echo "$TOKEN" | cleura login -u your_cc_username --token-stdin

To make sure your local installation of cleura works as expected, type:

$ cleura whoami
ID:        12345
Username:  mpapadop
Name:      Mesos Papadopoulos
Email:     mesos.papadopoulos@cleura.com
Admin:     true
Currency:  EUR
Profile:   default

If cleura can indeed connect to the Cleura Cloud REST API, you will get information regarding the authenticated user.

To get general help regarding cleura, type:

cleura --help

For an overview of all available commands and flags, refer to the command reference.