Application Registration

When creating a custom application that utilizes the CloudLink APIs, there are three levels of application certification that are available with different benefits and restrictions:

Mitel Self-Assessed

Any application that uses the CloudLink APIs and has not been submitted for review to Mitel will be considered to have been self-assessed by its developer to ensure that it follows Mitel's best practices. Self-assessed applications are subject to the following restrictions:

• Support is provided exclusively through the Developer Forum and there is no guarantee of resolution or service level agreement.

• If an application is determined to be violating any of Mitel's best practices, the CloudLink account where it is deployed may be locked without warning or notification. This will result in all CloudLink services being unavailable for all applications on that account, including Mitel applications.

• The Mitel Authentication Portal is not available for use with self-assessed applications.

Mitel Compatible

Mitel Compatible applications have undergone a review by the CloudLink team and reviewed to ensure that it is following best practices. Having a Mitel Compatible application offers to the following advantages:

• Support for the CloudLink APIs through the Developer Forum with formal tracking of confirmed bugs, and a response within 2 business days of raising an issue.

• In the event that an application is causing an issue with CloudLink, its publisher will be notified prior to any action being taken to disable the CloudLink account or application.

• Optional inclusion in the Mitel Applications and Integrations Gallery.

The review process requires the following:

• Send a direct message through the Developer Forums to Kevin Ferriss.

• Schedule a 1 hour call with the CloudLink API Team to document your application, including:

  1. Functionality overview, including architecture diagram

  2. Technology Stack

  3. APIs and resources utilized

  4. Logging and performance management

• Be prepared to make minor changes to your application if requested. In the case of user authentication, you will need to switch to the Authorization Code Flow on app approval.

On final approval, you will receive a unique clientId or "application identifier" that is required for API authorization and authentication anywhere the application/integration has been deployed and this may require you to switch your application's authentication method to use the Authorization Code Flow once approved.

Note - The timeline for this process varies, however Mitel will make a best effort to create a clientId within 5 business days of an application being approved.

Mitel Certified

Mitel Certified applications are created through a formal partnership between Mitel and a third-party developer or Mitel Authorized Partner. Mitel Certified applications will undergo a complete code review and a full suite of testing and be granted additional privileges above those conferred upon Mitel Compatible applications.

For more information on developing a Mitel Certified application, please send a direct message through the Developer Forums to Kevin Ferriss.

Application Deployment

Mitel Self-Assessed applications do not require any special steps for deployment, however in order to deploy a Mitel Compatible or Mitel Certified applications, special steps must be taken. There are separate deployment steps depending on if you are a Mitel Authorized Partner who has been issued with a "Partner clientId" for your application, or if you are a third-party developer who has been issued with a "Global clientId".

Mitel Partners

Mitel Authorized Partners may develop and register applications for deployment on any Mitel CloudLink account that they own. On approval, a Partner will be issued with a Partner clientId that can be enabled on any CloudLink account that resides under the CloudLink Partner account as required.

This process requires that a user with the PARTNER_ADMIN role in the Mitel Authorized Partner account execute a series of API calls.

Important: This user will need to be able to successfully login directly to the CloudLink Account Console. If they are not able to, they should be able to access their user account through the CloudLink Account Console accessible via MiAccess and send the welcome/activation email to themselves in order to set a dedicated password.

For convenience, the following Postman collection has been created for this purpose: https://github.com/mitel-networks/developer-api-program/tree/CL-10280

• Download and import the Postman collection and environment

• In the 'Application Registration' environment, fill out the following 'current values':

  1. username - The email address of the user with the PARTNER_ADMIN role

  2. password - The password for the user with the PARTNER_ADMIN role

  3. PartnerPrimeAccountId - The numeric account number for account flagged as the 'Partner Prime Account' in the CloudLink Account Console (also accessible via MiAccess).

  4. accountIdGUID - The GUID formatted accountId for the account where the application is being enabled. This is displayed in the URL in the CloudLink Account Console when viewing the account properties.

  5. applicationId - The clientId for the approved application being deployed.

  6. appName - The desired name for the application when viewed on the customer account.

  7. appDescription - The desired description of the application when viewed on the customer account.

• Save any changes you made to the Environment.

• In the 'Application Registration' collection:

  1. Run the POST Auth Token API call

  2. Run the PUT Enable Application API call

     1. If you are not making use of the Mitel Auth Portal, delete the "redirectURIs" array from the request body.

     2. If you are making use of the Mitel Auth Portal, ensure that you have added the proper redirectURI values in the request body or users will not be redirected back to your application after being authenticated.

Verify that both API calls executed successfully and your clientId will now be enabled on the appropriate account and your application can be safely deployed.

Third Party Developers

Independent Software Vendors (ISV) may develop and register applications for deployment on a Mitel CloudLink account. On approval, an ISV will be issued with a global clientId that can be enabled on any CloudLink account as required. As all Mitel equipment and licensing is the responsibility of the Mitel Authorized Partner, they will need to be involved in order to enable the clientId on their customer's account using the process described above.

Mitel Customers

If you are a customer, any custom application will need to be deployed through a Mitel Authorized Partner. To locate a Mitel Authorized Partner or service provider in your area click here or call us at one of our regional offices throughout the world.

Supported Environments 

At this stage Mitel supports MacOS, iOS, Android, and Windows based applications on the CloudLink API.

Development Environments

See Getting Started - Development Environments

Best Practices

In order to deploy a custom application in a production CloudLink environment the following best practices must be followed. If an application does not adhere to these best practices, it risks being blocked from CloudLink and any CloudLink accounts where it has been deployed may be temporarily disabled. Applications modified after the fact to violate these practices may result in suspension of the associated CloudLink account(s).

Logging

• All errors should be logged and retrievable for support purposes

• When encountering an API error, the following information must be captured

  • Values of the x-mitel-correlation-id and x-amzn-requestId headers

  • Full error code and message

  • Timestamp and any devices/users involved.

  • For any media or call related errors, ensure you capture the CallId

• All timestamps must be in UTC ISO date times.

Error Handling

• All errors should be captured with full details (see Logging)

• The context of the error should be evaluated to determine if there is a reasonable chance of success on retry. If there is no reasonable chance of success, no further retry attempts should be made.

  • The most appropriate errors for retries are: 408, 429, 503, 504, 598, 599 and anything that specifies a retry-after header.

  • For valid retry scenarios, a delay of a minimum of 2 seconds should be introduced before retry with a maximum of 5 retry attempts.

• For HTTP 429 error handling (too many requests)

  • The ‘retry-after’ value in the response header should be considered the minimum retry time

  • A random ‘jitter’ must be added to the retry time. Sample JavaScript is included in the Authorization Code Flow (OpenID Connect) sample code.

Authentication

• The Authorization Code Flow must be utilized for all user authentication except:

  • For Mitel Self-Assessed applications which do not have a clientId.

  • During initial development of Mitel Compatible and Mitel Certified applications as no clientId has been issued to you yet.

  • When using “grant_type” = “client_credentials” to authenticate as a Client from a server side application.

• Any tokens provided by CloudLink should not be manually decoded. This behaviour is strictly forbidden and if detected, your CloudLink account will be suspended.

Webhooks & WebSocket

• WebSocket connections must be utilized wherever possible. WebSockets are mandatory for client side connections to the Notification API.

• Webhooks can be utilized for sever side applications as a last resort