Cloudmore Systems API Guide

Cloudmore Systems API enables integration with other business systems using the latest web standards.

This document describes the overall principles around the Cloudmore Systems API and authentication steps that are prerequisite for making the actual requests to the API. The implementation details, such as description of the API request parameters and response types plus various examples are available from https://api.cloudmore.com/swagger.

Key Points for Authentication

• Authentication server endpoint url: https://api.cloudmore.com/connect/token
• Authentication standard: OAuth 2.0
• Access token format: JWT (JSON Web Token), more info available at https://jwt.io/

Key Points for Systems API Use

• Systems API url: https://api.cloudmore.com/api
• Systems API documentation: https://api.cloudmore.com/swagger
• Supported content-type: application/json
• Supported request types: GET (list or get details), POST (create), PUT (update), DEL (delete)

General Flow

1. Customer requests the access to the Systems API.
2. Cloudmore enables the access and returns all needed details for accessing the API to the customer.
3. User requests access token by authenticating against the Cloudmore Oauth2 authentication endpoint using the information provided by Cloumore.
4. Cloudmore Oauth2 authentication endpoint returns an access token in JSON Web Token format.
5. User passes the returned authentication token in the Authorization header of each request made to the Systems API.
6. If the access token expires, new token must be requested from the Cloudmore OAuth2 authentication endpoint.

Request a REST API secret & reseller ID

Raise a support ticket requesting a REST API secret key and reseller ID by emailing support@cloudmore.com or filling in the support form below:

Click on the icon in the top right-hand corner.

Select support, and complete the form.
Click submit feedback

You will receive a confirmation email with a ticket reference number.
Cloudmore support will process your request and email you an API secret and your reseller ID.

Contact support@cloudmore.com, quoting your reference number if required.

Create Systems API admin

Create a new Cloudmore Administrator - (see the guide here). 
It is recommended that you set a complex password as this is used in the API calls

Click on more and scroll to bottom of form.
Tick the allow REST API access.

Security

Cloudmore has built the security on OAuth2 standard grant type called “client credentials.” OAuth 2.0 is the industry-standard protocol for authorization and enables a secure authentication between Cloudmore and your 3rd party system.

Your 3rd party system needs to be able to handle the authentication request from Cloudmore and issue an access token in JSON format (a JSON Web Token or JWT).

Cloudmore has developed this using IdentiyServer4 (http://docs.identityserver.io), an OpenID and OAuth 2.0 framework for ASP.NET Core. This is one example of how the OAuth2 framework can be used.

To further ensure the security, all data is encrypted in transmission, all requests must be performed over HTTPS. 

Authentication

Each request made to the API methods must have a special authorization header “Bearer” with the JSON Web Token (JWT) that identifies current user and contains other information such as the user name and role.

For retrieving the authentication token a HTTPS POST request has to be made to the authentication server endpoint with following details.

POST <authentication_server_host>/connect/token

Content-Type: application/x-www-form-urlencoded

Request Parameters

Name	Value
client_id	“ro.customer.client”
client_secret	Client secret given by Cloudmore to the API user. The secret must be requested from Cloudmore separately from this document.
grant_type	“password”
scope	“api”
username	Reseller account user name. Username must be for the account for which the REST API access has been enabled.
password	Reseller account password for the account for which the access via REST API has been enabled.

 

If the parameters are correct, the authentication server returns a JWT access token which is a JSON object with following content:

JWT Access Token

Name	Value
access_token	Base64 encoded string containing the access token. The whole token must be passed in the header of the all the requests made to the Cloudmore REST API.
expires_in	Time in seconds the access token is valid. After the token has expired, new token must be retrieved by repeating the process described in this chapter.
token_type	“Bearer”

 

More info about all the fields of the access token can be found here: https://jwt.io

If the input data for retrieving the access token is incorrect, authentication server responds with corresponding error code and description of the error. For example, if the password provided in the POST request parameter “password” is incorrect, the authentication server endpoint returns an HTTP error 400 “Bad request” with description of the error in JSON object {"error":"invalid_grant","error_description":" The user name or password is incorrect."},

Unsuccessful Authentication Error Codes

Error Code	Error Description	Solution
400	{"error":"invalid_grant","error_descripti on":"The user name or password is incorrect."}	Verify that the username and password are correct.
400	{"error": "invalid_scope"}	Verify that the POST parameter “scope” has correct value.
400	{"error": "unsupported_grant_type"}	Verify that the POST parameter “grant_type” has correct value.
400	{"error": "invalid_client"}	Verify that the POST parameters “client_secret” and “client_id” have correct values.

 

Using access tokens for accessing Systems API methods

After successful authentication, the returned access token must be passed in the “Authorization” header of each request made against Cloudmore Rest API. The format of the authorization header is following:

Authorization: Bearer <access_token value>

Example request for retrieving all organizations of the Reseller:

GET <rest_api_host>api/resellers/ca6430d3-7f6a-0049-8075-72921f062eb8/Organizations

Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjE5YTk4Yzc2U1… (part removed for brevity)

Content-Type: application/json

If the request was processed successfully, a corresponding HTTP response code is returned together with the result in JSON format, otherwise an appropriate HTTP error code is returned.

Code	Description
200 OK	Request was successful and requested info is in the response.
201 Created	Object was successfully created.
204 No content	Object was successfully updated or deleted.
401 Unauthorized	The access token passed in the authorization header is either invalid or expired.
404 Not found	Requested information was not found.
400 Bad request	The request contains missing parameters or they are in wrong format.