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.

Without 2FAWith 2FA

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.compliant.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.compliant.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.compliant.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.compliant.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.compliant.cleura.cloud/accesscontrol/v1/openstack/domains endpoint:

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

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

[
  {
    "area": {
      "id": 4,
      "name": "CityCloud Compliant Sto1hs",
      "tag": "STO1HS",
      "regions": [
        {
          "zone_id": 103,
          "name": "Sto1 HS",
          "status": "active",
          "region": "sto1hs"
        }
      ]
    },
    "id": "b7c3998142f0496aa3582d8a3ae9ae1e",
    "status": "provisioned",
    "name": "CCP_Domain_123C456",
    "enabled": true
  },
  {
    "area": {
      "id": 1,
      "name": "CityCloud Compliant Sto2hs",
      "tag": "STO2HS",
      "regions": [
        {
          "zone_id": 101,
          "name": "Sto2 HS",
          "status": "active",
          "region": "sto2hs"
        }
      ]
    },
    "id": "2d04a791db0e4a799b65c3794eda09bf",
    "status": "provisioned",
    "name": "CCP_Domain_123C456",
    "enabled": true
  },
  {
    "area": {
      "id": 5,
      "name": "Cleura STO-COM",
      "tag": "STO-COM",
      "regions": [
        {
          "zone_id": 104,
          "name": "Stockholm Compliant",
          "status": "active",
          "region": "sto-com"
        }
      ]
    },
    "id": "989d137c832c42eb9a6c6839a5c28675",
    "status": "provisioned",
    "name": "CCP_Domain_123C456",
    "enabled": true
  }
]