Header Logo

Developer Portal

CloudLink Account

In order to utilize the CloudLink API, you must:

  • Have a CloudLink Partner account.

  • Have an account administrator user that can be used to obtain authorization token

  • If you are utilizing an integration with a Mitel product such as a PBX, MiCollab, or MiContact Center, and wish to make use of that integration with the API, the user used to access the API must be associated with the account where the integrations are configured.                

If you do not have a CloudLink account, login to MiAccess and click ‘CloudLink Accounts Console’ on the navigation menu to automatically create your account. For more information on creating CloudLink accounts and users, please see the CloudLink Accounts documentation found here.

API Call Structure

While this guide will walk you through how to use the CloudLink API, it is recommended that you first familiarize yourself with the basics of REST, if you're not already. A very useful tool for designing and testing API calls is Postman, for which we have a library of API calls you can download. To successfully make a call to the CloudLink API, your call will need several things:     

  • Authentication Token - A unique, time sensitive token generated by the Authentication API and used to make most API calls.

  • Endpoint – The destination for the API call, formatted as a URL.

  • Method - Also known as the 'HTTP Verb', this determines if you are creating(POST), reading(GET), updating(PUT), or deleting(DELETE) something.

  • Headers – Additional instructions for the API call, typically containing information required by the server receiving the call:

    • Authorization – Used to send the authentication token

    • X-Mitel-App – A custom header that identifies the application that is making the API call

    • Content-Type – Outlines the data format expected in the response from the API, and while a good practice to always include, it’s not always strictly required by every endpoint.

  • Request Body – Contains the data that you are sending to the API (in JSON format).

Authentication

Any application or integration built using CloudLink APIs must obtain an authentication token and refresh this token periodically.  Applications/integrations built without this token will be rejected/blocked from using the platform.

IMPORTANT: All custom applications and integrations that require user authentication MUST use the OpenID Connect Flow which is elaborated on in the Authentication API Guide and for which sample code is available. The simple OAuth 2.0 grant method is described below which is useful for authenticating clients (See Admin API Guide) and testing the APIs using tools such as Postman.

Getting a Token (OAuth 2.0)

In order to obtain a token, a request must be made to the Authentication route as shown in the example below. Once a token has been obtained, this token must be used in the Authorization header for all subsequent calls into the other CloudLink REST APIs. Clients must obtain an authentication token to submit requests to the CloudLink Platform REST APIs.

The following is an example of a request to create a new authentication token:

Request: POST https://authentication.dev.api.mitel.io/2017-09-01/token Headers: Content-Type: application/x-www-form-urlencoded Body : grant_type  : password Username    : <Cloudlink Username> Password    : <Cloudlink Password> account_id  : <Account Id Associated with the Cloudlink User>

Response: HTTP 201 (Success) Body : “token_type’       : “bearer” “expires_in”       : 4090, “access_token”     : “eyJhY2NvdW50SWQiOiIxMDU5OTAwNDUiLCJiZWFyZXJUb2tlbiI6I…”, “refresh_token     : “eyJhY2NvdW50SWQiOiIxMDU5OTAwNDUiLCJiZWFyZXJUb2tlbiI6Im…”, “scope”           : “read write”

For more information on different ways to create a token please read the auth API section.

Refreshing a token

Since authentication tokens expire after a set period, they will need to be refreshed periodically. Unlike the initial token, you have the option of using the ‘refresh_token’ provided with the most recent ‘access_token’ to obtain a new token without requiring user credentials. To do this, use the same API call as above with some changes to the request body. Here’s an example: 

Request:  POST https://authentication.dev.api.mitel.io/2017-09-01/token  Headers:  Content-Type: application/x-www-form-urlencoded   Body :  grant_type: refresh_token  refesh_token: “eyJhY2NvdW50SWQiOiIxMDU5OTAwNDUiLCJiZWFyZXJUb2tlbiI6Im…” 

While you can set your workflow to attempt a refresh after the appropriate time has passed, Mitel’s recommended practices for the CloudLink API are: 

  • Initiate the token refresh after receiving an HTTP 401 error on an API call 

  • Retry the failed call and then resume normal function 

  • Include an exit condition in your code to avoid a stuck retry loop if the above continues to fail after a reasonable number of re-attempts. 

    • This is important as Mitel may temporarily disable your CloudLink account if your application makes too many re-attempts! 

Headers

Headers contain important meta-data about your API request, such as what type of data you're sending and receiving, as well as authentication information. While there are variety of headers involved with the various calls to the CloudLink APIs which you can find documented in the official API Documentation, the following headers are typically required for all CloudLink API calls:

Authorization

The authorization header contains the bearer token obtained through the Authentication API, the process for which is described here and again in the Authentication API Guide.

X-Mitel-App

Any application or integration built using CloudLink APIs must contain a unique header that identifies the application to the platform, labelled "X-Mitel-App". Applications or integrations built without this information will be rejected/blocked from using the platform.

The header must follow the following format for all REST API requests:

Getting Started 1
  • appName should use a pattern of “app-flavor” in all lower case where:

    • App - Name of the application

    • Flavor - Values like web, desktop, android, ios, etc.

  • appVersion should use what makes sense for the release or build nomenclature. The suggestion is to follow Semantic Versioning (SemVer) where possible.

  • platform will consist of “os/osVersion” where:

    • os - one of the following exact values: windows, linux, mac, ios, android. No abbreviations are accepted.

    • osVersion = exact version of the operating system (e.g. 10.0.19041)

  • session will consist of an automatically generated 128-bit GUID for the session ID (e.g. e769f6ec-ceb6-4b98-bab5-2dc0e720426c) that is unique to the specific instance of the application (e.g. a process in a browser, or an app on a desktop), and is immutable for the lifetime of that instance.

Important: The entire string must be lower case.

The following is an example of this header:

x-mitel-app: meetings-desktop/1.0.4/;platform=windows/10;session-id=b49d5f6c-1d31-4816-9c77-3d991c335220

Content-Type

The content-type is the format of the data being provided in the request body of the API call (often called a MIME type). With the Mitel CloudLink API this will typically be “application/json” however there are exceptions to this rule (e.g. GET Token uses “x-www-form-urlencoded") and it’s not always strictly required. Always refer to the API Documentation for details.

In some cases you may see two references to content-type/contentType, where one is a header indicating the data format of the request body, and the other is included in the request body itself and refers to the data format of a particular object. For example, when creating a chat message you will need to indicate in the Content-Type header that the request body is “application/JSON”, but also indicate in the request body that the chat message is “text/plain”.

Endpoints

An endpoint is the ‘end’ of a communication channel, such as an application making a request or the server that the request is being sent to. In the context of Mitel’s REST API, the endpoint is the URL for the API call that you wish to make. For example, the endpoint for chat conversations is:

https://chat.api.mitel.io/2017-09-01/conversations

This URL consists of three different components:

Host URL - https://chat.api.mitel.com

Base Path - /2017-09-01

Path - /conversations

In some cases you can also include additional query parameters such as filtering, ordering, and explicitly defining which properties you wish to return.

Methods

HTTP Methods, also referred to as HTTP Verbs, indicate what kind of operation you are performing. While there are 8 methods within the REST model, there are only four methods that you will use with the CloudLink API:

GET - Used when 'reading' information about an existing resource. Typically does not require a request body, but usually allows you to use query parameters to search, filter, or otherwise control the data that is returned.

POST - Used when 'creating' a new resource. Typically requires a request body.

PUT - Used when updating an existing resource. Typically requires a request body.

DELETE - Used when deleting an existing resource. Typically does not require a request body.

Request Body

The request body can generally be considered as the content of the API call that you’re making. The request body must follow a set format which is defined in the API Documentation for each endpoint/API call. Here’s an example JSON request body for the “Create Message” endpoint:

{ "body": "Hello World.", "contentType": "text/plain"   "fallbackText": "Something went wrong", }

Some API calls do not require a request body, in which case the information that’s needed to make the API call is included entirely within the HTTP request itself. A good example is when you use the GET Users API call, where you wish to order the results by a last name:

https://admin.dev.api.mitel.io/2017-09-01/accounts/{accountId}/users?$orderby=lastname

When combined with the headers, this is sufficient to complete the API call and no request body is needed.