CloudCherry is now part of Cisco.
Learn More About Cisco

Authentication

API Authentication

There are two ways to authenticate the API, Basic Authentication and OAuth2. The easiest way to authenticate is using HTTP Basic authentication. Enter your username and supply your password or API Key as the password.

Example Basic Auth

curl -u <USERNAME> https://api.getcloudcherry.com/api/questions

Get a Bearer token by using the LoginToken API.

Example OAuth

You can also use OAuth to obtain an access token.

OAuth Flow

CURL Command

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header \
'Accept: application/json' -d 'grant_type=password&username=<USERNAME>&password=<PASSWORD>' \
'https://api.getcloudcherry.com/api/LoginToken'

Request URL

https://api.getcloudcherry.com/api/LoginToken

Example Response Body

{
  "access_token": "qaLjSK8Fxa2vvLhsI-2un5HSpyuYpyJkpqtILA5n5mAb_6boH2kSN5k94Xdp9TTRPkEtXuI9E079KLPbNU7vuuiHNg7P1bN6lHQBXJbyI0s7V2lAzTfE6E2e2-Bl8BO3l-ACG2IO80lge4wR6r3QKQLSpeDagXc9z9ZQs1BEmS8Ceya9l-7HYlEtG4p7uuswwqwALvKC9oqtPQqg0NauRzA_yOxj6LId_UZoYrwbWdTNIPgbBPOQPuB0Tc7VhssPs_IyYEA7pIgSuSzR-gghNKHmEh_7vi_8kppeWxJeGdI5cpkSdDgPngOg7CT2UikGe5N9ZP7NHPjF8omTMimxHkQw6RDMWC7IMnehBU3ByGq7VapLoEAf5EDCYO82xVbBi3foq5fIF3yl8hrbZthkhilNx1hO9cYTmVj7Rwasxh0pPSFlpxCx8mez-4phU5j6TWvYBUroDeLIp6gsmzg6fFHjAI5I-vOGU4jkb-HOCcjvwPFUUukLGOH3HGny2YOYeGIwidII0mzgh-gxRfexXGk7JpSkZnIvuCizbJL1ihWze1gPgE0sfFYaofrhobTj4Ty9uA",
  "token_type": "bearer",
  "expires_in": 43199,
  "userName": "<USERNAME>",
  "email": "arvi@getcloudcherry.com",
  "primaryRole": "User",
  "managedBy": "manageruserid",
  "preview": "True",
  "station": "uswest",
  "hash": "ayoiY9J90Fg3Wbx0qjvaQoX03ngDUdxVd2cSZwh609o=",
  ".issued": "Mon, 22 Apr 2019 10:48:47 GMT",
  ".expires": "Mon, 22 Apr 2019 22:48:47 GMT"
}

Try It Live

Retain the “access_token” for rest of session(or until expiry). You will use the access token for making every other API call. Just add the header “Authorization: Bearer {access_token}” to every further API request to be identified as authorized.

Using API Keys

You may also generate an API Key using the GenerateAPIKey API.

curl -X GET --header 'Accept: application/json' 'https://api.getcloudcherry.com/api/GenerateAPIKey'

Try It Live

or obtain an existing API key using GetAPIKey

curl -X GET --header 'Accept: application/json' 'https://api.getcloudcherry.com/api/GetAPIKey'

Once you have an API Key, use the combination of your userid and API Key for authentication.

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header \
'Accept: application/json' -d 'grant_type=password&username=<USERNAME>&password=<APIKEY>' \
'https://api.getcloudcherry.com/api/LoginToken'

Try It Live

C# Login Token code

using Newtonsoft.Json;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
namespace TokenCreation
{
    public class Login
    {
        public async Task<string> LoginToken(string username, string password)
        {
            //Base URL
            string baseURL = "https://api.getcloudcherry.com";

           //URL to Create Token
            string endPoint = baseURL + "/api/LoginToken";
            HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, endPoint);
            var postvalues = new[] {
                    new KeyValuePair<string, string>("grant_type", "password"), // Nothing to change here
                    new KeyValuePair<string, string>("username", username), // Provide your CC Username
                    new KeyValuePair<string, string>("password", password)  // Provide your CC Password
                };
            request.Content = new FormUrlEncodedContent(postvalues);
            var httpClient = new HttpClient();
            var response = await httpClient.SendAsync(request);
            string responseBodyAsText = null;
            if (response != null && response.IsSuccessStatusCode)
                responseBodyAsText = await response.Content.ReadAsStringAsync();
            else return null;
            var logintoken = JsonConvert.DeserializeObject<Dictionary<string, string>>(responseBodyAsText);
            logintoken.TryGetValue("access_token", out string accessToken); // Access token to be used in

            // further API calls as Bearer Token       
            return accessToken;
        }
    }
}

Token Validity

By default, the access token is valid for 24 hours. This setting can be configured at an account level using Enterprise Security settings to have a shorter life.

Expired tokens receive a HTTP 401 response

{
  "message":"Authorization has been denied for this request."
}

A recommended practice for OAuth bearer tokens is to use one until you receive an expired response. Upon receiving an expired response, request a new token for your next API call. Tokens are not invalidated when new tokens are requested and can be used up to their expiration.

Security

Your bearer token and API Key are sensitive information that can be used to compromise your CloudCherry account. Treat these like username/passwords, and do not hardcode them in your source code. A recommended practice would be to use them as environment variables in server side code. Do not distribute these in mobile or desktop apps since these can be extracted by decompiling binaries.