Training Guides

Cloudmore Systems API Guide

Why do this.

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.

Important

Cloudmore only provides detailed information about how to setup the Systems API and the description of the API calls. It’s the user’s responsibility to provide and manage the systems to interface with the API. Cloudmore has created a solution, built on standard, available technologies, and workflows. Cloudmore cannot incorporate bespoke configuration or changes.

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.

 

Activate the Systems API add-on

Log in to Cloudmore.
Navigate to your reseller menu,
then click on reseller and select add-on’s.

Systems API 1.1.png

Tick to select “Systems API Access”

The cost will show in your local currency and will be charged at this rate after your free trial expires.  Click update.

Systems API 1.2.png

 

Request a REST API secret & reseller ID

Raise a support ticket requesting a REST API secret key and reseller ID.

Click on the Systems API 1.3.pngicon in the top right-hand corner.

Systems API 1.4.png

 

 

Select support, and complete the form.
Click submit feedback

Systems API 1.5.png

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 guide)  http://web.cloudmore.com/guides/how-to-add-administrators
It is recommended that you set a complex password as this is used in the API calls

Systems API 1.6.png

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

Systems API 1.7.png

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.

 

END

Tags: API

Cloudmore Systems API Guide

Why do this.

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.

 

Important

Cloudmore only provides detailed information about how to setup the Systems API and the description of the API calls. It’s the user’s responsibility to provide and manage the systems to interface with the API. Cloudmore has created a solution, built on standard, available technologies, and workflows. Cloudmore cannot incorporate bespoke configuration or changes.

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.

 

Activate the Systems API add-on

Log in to Cloudmore.
Navigate to your reseller menu,
then click on reseller and select add-on’s.

Systems API 1.1.png

Tick to select “Systems API Access”

The cost will show in your local currency and will be charged at this rate after your free trial expires.  Click update.

Systems API 1.2.png

 

Request a REST API secret & reseller ID

Raise a support ticket requesting a REST API secret key and reseller ID.

Click on the Systems API 1.3.pngicon in the top right-hand corner.

Systems API 1.4.png

 

 

Select support, and complete the form.
Click submit feedback

Systems API 1.5.png

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 guide)  http://web.cloudmore.com/guides/how-to-add-administrators
It is recommended that you set a complex password as this is used in the API calls

Systems API 1.6.png

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

Systems API 1.7.png

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.

 

END

Comments or suggestions?