API User Guide

You can now use CloudCheckr CMx access tokens when running API calls in our legacy product. You can still use your existing API access keys in the legacy product, but access tokens will provide better security, more consistent authorization management, and the ability to access multiple projects and accounts.
Please use these URLs when accessing the API in the following platforms:
  • AU: https://au.cloudcheckr.com
  • EU: https://eu.cloudcheckr.com
  • GOV: https://gov.cloudcheckr.com
  • FED: https://fed.cloudcheckr.com

CloudCheckr provides users with a REST-compliant API, allowing them to access and manipulate the data in their CloudCheckr account programmatically. The API uses the HTTPS protocol to make requests and return responses in a JSON or XML format.

CloudCheckr is revamping its API documentation to ensure that it reflects the best practices for REST and to improve overall consistency. We will restructure each call to include these sections:
Section Description
Input Parameters Options that you pass with the endpoint to influence a response.

Identifies if a parameter is required or optional, the data type, and the parameter description.
API Call URL Identifies the common path for the API (highlighted in yellow) and the end path of the endpoint (highlighted in light blue).
Request Example Includes a sample request that shows the endpoint and a few key parameters.

Formatted in curl since it’s language-agnostic.

Includes the header information and the method (GET or POST in most cases).
Response Example Shows a sample response for all of the parameters passed in the request example.

Includes examples in XML and JSON.

Authentication

Authentication to API endpoints is secured via randomly generated hashes. Access keys are generated and revoked within the webapp. Access keys are the SHA512 HMAC of two randomly generated 32-byte strings. Access keys are, in effect, secret keys and should not be shared. Anyone with knowledge of the access key will be able to make API calls against the associated account.

Creating API Access Keys

CloudCheckr offers two distinct API access keys: admin-level and account-level. These two keys allow for different access permissions. An admin-level API key can be used by a user to make calls against any of the cloud provider accounts in CloudCheckr. An account-level API key can only make calls against a single account.

Create An Admin-Level Access Key

  1. Login to CloudCheckr as an administrator.
  2. From the header bar, click the Admin Functions icon and select Admin API Keys from the menu. The Admin API Access Keys page opens.
  3. Click the New Admin Access Key button. The application generates your access key and displays it on the page.

Create An Account-Level Access Key

  1. Login to your CloudCheckr account.
  2. From the landing page, select the account for which you want to generate the API access key.
  3. From the left navigation pane, choose Account Settings > API Access Keys. The API Access Keys page opens.
  4. Click the New Access Key button. The application generates your access key and displays it on the page.

Disabling/Enabling API Access Keys

Existing API access keys can be disabled and/or enabled at any time. Disabled access keys will not be able to make any calls against CloudCheckr. Any calls made using disabled access keys will return no data.

Disable or Enable Admin-Level Access Keys

  1. Login to CloudCheckr as an administrator.
  2. From the header bar, click the Admin Functions icon and select Admin API Keys from the menu. The Admin API Access Keys page opens.
  3. Locate the access key you would like to disable or enable.
  4. Toggle the active switch to on or off.

Disable or Enable Account-Level Access Keys

  1. Login to your CloudCheckr account.
  2. From the landing page, select the account for which you want to generate the API access key.
  3. From the left navigation pane, choose Account Settings > API Access Keys. The API Access Keys page opens.
  4. Locate the access key you would like to disable or enable.
  5. Toggle the active switch to on or off.
    6. This setting auto-saves and takes effect immediately.

Compromised or Revoked Access Key

If for any reason you believe an access key has been compromised or you want to revoke access to the API from someone with an access key, you can revoke the access key. API keys can be created and revoked as often as needed.

Revoke Account-Level API Access Keys

  1. Login to your CloudCheckr account.
  2. From the landing page, select the account for which you want to revoke the API access key.
  3. From the left navigation pane, choose Account Settings > API Access Keys. The API Access Keys page opens.
  4. Locate the access key you would like to revoke.
  5. Click the Delete button to the right of the access key.
  6. Click the Confirm button.
Once an access key is revoked, it cannot be used to make any calls against CloudCheckr. Revoked access keys cannot be restored. A new access key must be created.

Creating Temporary Access Keys

Because access keys can be created and deleted as often as possible, it is recommended no applications or individuals share an Access Key. This makes it simple to create and revoke temporary Access Keys. To create a temporary Access Key, create the key, share with the application or individuals that need to use it. Then revoke the Access Key when it is no longer needed.

Calling the CloudCheckr API

CloudCheckr only supports API requests using HTTPS. Any attempts to access the API through HTTP will fail.

Methods for Calling the API

You can use the CloudCheckr API using a variety of tools. Tools such as curl can be used to programmatically script the CloudCheckr API. You can use software like Firefox to query the API using a web browser.
Example Using Curl

curl 'https://api.cloudcheckr.com/api/best_practice.xml/get_best_practices?access_key=00XXXXXXXXXXXXXXXXXXXXXXXXXXX'

Example in Firefox

https://api.cloudcheckr.com/api/best_practice.xml/get_best_practices?access_key=00XXXXXXXXXXXXXXXXXXXXXXXXXXX

Result

<BestPractice>

              <BestPracticeName>

              	Auto Scaling Groups Not Using Cooldown Period

              </BestPracticeName>

              <ShortDescription>

              	Checks each Auto Scaling group to verify they are configured to utilize cooldown periods. Lists each group that does not.

              </ShortDescription>

              <LongDescription>

              	<p>When enabled, Auto Scaling will automatically scale EC2 capacity up or down, according to pre-defined conditions. During period of high-demand, the number of EC2 instances will increase to meet that demand. When there is little or no demand, the number of instances decreases to help minimize costs. </p><p>Cooldown periods help to prevent Auto Scaling from initiating additional scaling activities before the effects of previous activities are visible. Because scaling activities are suspended when an Auto Scaling group is in cooldown, an adequate cooldown period helps to prevent a trigger from firing based on stale metrics. If a cool-down period is not configured, the scaling policy may scale up and down too quickly. </p><p><a href="http://docs.amazonwebservices.com/AutoScaling/latest/DeveloperGuide/scaling_plan.html#scaling_policies" target="_blank">Go here to learn more.</a></p>

              </LongDescription>

              <Category>

              	Usage

              </Category>

              <Importance>

              	Low

              </Importance>

              <CountOfResults>

              	2
              </CountOfResults>

              <Results>

                  <Result>

                  	Auto Scaling Group: agcmgroup | Cooldown: 1 second(s) | Region: US East (N. Virginia)

                  </Result>

                  <Result>

                  	Auto Scaling Group: changemon | Cooldown: 1 second(s) | Region: US East (N. Virginia)

                  </Result>

              </Results>

          </BestPractice>

Returning Results From the API

Results from the API can be returned in JSON or XML.

In the example call below:

https://api.cloudcheckr.com/api/help.xml/get_all_api_endpoints

The ".xml" content type in the endpoint URL tells the API to return the results in XML. To return the results in JSON, simply switch the content type:

https://api.cloudcheckr.com/api/help.json/get_all_api_endpoints

API Post Requirements

When sending API requests via POST method, the request needs to be set up as follows:

  • You must add the Content-Type to the request headers
  • You can pass the access_key parameter as a query string or in the request headers (latter recommended!)
  • The parameters must be sent in the body of the request in the appropriate content type format

See the following example request below.

POST /account.json/get_account

          Host: localhost

          Accept: application/json

          Content-Type: application/json

          access_key: access_key_here

          
          {

            "account_name": "dummy_account"

          }

API Pagination

When you select from the API, it returns up to 100 results. If you have more than 100 results, you will have 2 additional fields in the results.

The 2 additional fields are:

  • HasNext - boolean value indicating if you need to call the API to get more results.
  • NextToken - the string you should pass to the function to get additional results.

For example, you call the API here to get a list of EC2 instances:

https://api.cloudcheckr.com/api/inventory.xml/get_resources_ec2_details?access_key=[access_key]

You receive back the following response:


          <?xml version="1.0"?>

            <GetResourcesEc2DetailsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

               <HasNext>true</HasNext>

               <NextToken>H4sIAAAAAAAEAJWQQQvCMAyF</NextToken>

               <DateOfResults>2014-08-31T16:21:34</DateOfResults>

               <Ec2Instances>

               ...<snip>...

Notice the 2 new fields. Under Ec2Instances, you will have the first 100 results. To retrieve the next 100 results, send the new URL.

https://api.cloudcheckr.com/api/inventory.xml/get_resources_ec2_details?access_key=[access_key]&next_token=H4sIAAAAAAAEAJWQQQvCMAyF

You will receive back the following response:

<?xml version="1.0"?>

             <GetResourcesEc2DetailsResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

             
                <HasNext>true</HasNext>

                <NextToken>KLSDJFLIEDLKNEI</NextToken>

                <DateOfResults>2014-08-31T16:21:34</DateOfResults>

                <Ec2Instances>

                ...<snip>...

To get the following set of 100 results, generate and submit the next URL using the next_token.

https://api.cloudcheckr.com/api/inventory.xml/get_resources_ec2_details?access_key=[access_key]&next_token=KLSDJFLIEDLKNEI

Continue this process until you receive back a response with:

<HasNext>false</HasNext>

Errors

Error codes are returned as text in the HTTP content. Look for the field "ErrorMessage" and "ErrorCode" for error messages.

How did we do?