API & Integrations - Managing API 1.0 for Cloud Gateway

This guide describes how administrators responsible for adding and managing the API applications your organization has developed can add, change, enable, disable, and delete API applications in the Administration Console. It is intended for Administrators.

For details on Mimecast's API Function Calls and Response-Codes, see the detailed API Integrations Documentation here. 

API Application Concepts at Mimecast

• Mimecast uses role-based access with our API. Similar to the Administration Console, rights to any resource are controlled by a role to which a user is assigned. API calls are then made on behalf of this user. 
• API applications and API permissions are defined separately. Mimecast's API makes use of four keys when making any API call. Two keys identify the API application itself (API Application ID and Key, e.g., "MySIEMTool"), and two identify the associated user account trying to make the call (Access Key and Secret Key, e.g., MySIEMServiceAccount").
• When a user's password is changed, or the account is disabled, any set of Access keys and Secret Keys for that user will also be revoked. A new set of Access and Secret Keys will need to be generated to continue making API calls. 
• Only Mimecast Administrator roles can generate API Keys; if your Administrator Authentication Profile has SSO enabled, you must disable the SSO, generate the keys, and then enable SSO again.
• When setting up all four keys for a new API application, there is a 30-minute period between API Application ID and Key generation and being able to generate Access and Secret Keys. This guide provides a set of prerequisite steps to perform within that window as part of the Creating User Association Keys section. 

Accessing Your API Applications

To access your API Applications:

1. Log on to the Mimecast Administration Console.
2. Navigate to Services | API and Platform Integrations.
3. Click on the Your API 1.0 Applications tab.

From the Your Application Integrations tab, the below actions can be carried out:

• Add an application
• Edit an application
• Delete an application

Adding an API Application

To add an API Application:

1. Select your desired API from the available options from the Available Integrations tab, or choose the Mimecast API 1.0 tile if you're creating your own custom API.
2. Fill in the Details section as outlined below:

These fields will be automatically populated and cannot be edited if they click on a named integration.

 

Field / Option	Description
Application Name	Provide a name for the application to identify it later quickly.
Category	Select a category for the application from the drop-down menu. This field is informational and will not affect the functional capabilities of the API application.  SIEM Integration: Relates to security information and event management (SIEM), which provides real-time analysis of security alerts generated by the application. MSP Ordering & Provisioning: Assists with provisions for the Managed Service Provider (MSP) Portal, available for select Partners to manage customers. Email / Archiving: The application relates to the messages and files stored in Mimecast. Business Intelligence: The application's infrastructure and tools enable information access and analysis to improve and optimize decisions and performance. Process Automation: The application allows the automation of business processes. Other: Select this option if the application doesn't fit with any of the other categories.
Service Application	If the "Enable Extended Session option" is selected, Access keys generated for the application will no longer expire based on the Authentication Profile's Authentication TTL value. This is recommended for integrations with a valid access and secret key pair to call the API frequently using just authorization.
Description	Describe what the application is for or does.

3. Click Next.
4. Fill in the Settings section as outlined below:

 

Field / Option	Description
Technical Point of Contact	Name of a person or group who should be contacted if Mimecast needs to speak with the maintainer of this API application.
Email	Email address of the person or group who should be contacted if Mimecast needs to speak with the maintainer of this API application.
Opt-In	This option lets you receive updates as our API capabilities and integration change over time.

5. Click Next.
6. Review the Summary page to ensure all details are correct. To fix any errors:

• • Click the Edit link next to the Details or Settings to return to the relevant page.
  • Make changes and click the Next button to proceed to the Summary page again.

7. Click on the Add button. The application's details are displayed in a slide-in panel.

A confirmation is displayed that your app has been created with the Application ID and Application Key. These keys identify the application you’ve added.

8. Copy and paste the Application ID and Key to a safe place for use later in the process.
9. Wait 30 minutes and click on the application in your list. A panel opens.

• • While waiting for the application to become live, you may go through the Prerequisites section of Creating User Association Keys. 

10. Click on the X to return to the list of API applications.

Creating User Association Keys

User Association Keys are specific to a user within Mimecast, and all API calls are managed based on that user's level of access within Mimecast. When creating user association keys, we recommend creating a user for making API calls, such as a service user account (e.g., [e-mail]). The reasons for this recommendation are: 

• Authentication: Only SMS and email two-factor authentication mechanisms are supported when generating user association keys. Mimecast's most common authentication configuration is an identity provider or SAML assertion. Having a service account, users can apply a different or custom set of authentication requirements.
• Access: By using a service account, the administrative rights within Mimecast can be scaled to only be performed necessary actions and are not tied to a specific person's access. 

• Only Mimecast Administrator roles can generate API Keys; if your Administrator Authentication Profile has SSO enabled, you must disable the SSO, generate the keys, and then enable SSO again.
• If the password for the account used to generate a Key is reset, the Keys will also expire. Using a dedicated service account lessens that risk.

Prerequisites 

Creating a service account user:

The Admin role must be assigned before generating keys, or you will receive the following error:
"Sorry, something went wrong. Please close this page and try again. If the issue persists, contact Support."

The service account user does not need a mailbox or access to mail flow to function unless you plan to use email as a two-factor authentication mechanism. A misconfigured Service account will produce the following error: "The supplied address may not be used for this purpose."

To create a new service account user: 

1. Navigate to Directories | Internal Directories.
2. Click on the domain the user will be added to.
3. Click New Address. 
4. Complete the user's Email Address.
5. Enter a Password and Confirm Password. You will need to remember this password for use later in this article. 
6. Click Save.

• If You have SAML configured in either the Administrator Authentication Profile or the Authentication Profile tied to the service account, the following error may occur: The supplied address may not be used for this purpose.
• Only Mimecast Administrator roles can generate API Keys; if your Administrator Authentication Profile has SSO enabled, you must disable the SSO, generate the keys, and then enable SSO again.

Granting API Service Account User Permissions

Each API call has a prerequisite section that tells you what permissions are needed. Usually, a Basic Administrator role will suffice, allowing you to use the same API keys generated for multiple API calls under the application.  

• The setup guide outlines the permissions for the associated API call for existing integrations.
• Only Mimecast Administrator roles can generate API Keys; if your Administrator Authentication Profile has SSO enabled, you must disable the SSO, generate the keys, and then enable SSO again.

If you want to create a custom administrative role for this API service account user: 

1. Navigate to Account | Roles. 
2. Click New Role.
3. Enter a Role Name and Description.
4. In the Application Permissions section, select the boxes for each required role used by the service user account. 
5. Click Save and Exit. 
6. Locate the newly created role and click on the role name. 
7. Click Add User to Role. 
8. Click on the email address of the API service user account.

If you want to add the service account user to an existing role:

1. Navigate to Account | Roles. 
2. Click on the Administrator role the user will be added to. 
3. Click Add User to Role.
4. Click on the email address of the API service user account.

Generate Access and Secret Keys:

1. Click on API Application from the application list.
2. Click Create Keys. A "Create Keys" wizard is displayed with the Account tab selected.
3. Enter the Email Address of your service account.

You'll need to know the service account's domain or cloud password for the next step.

4. Click Next. 
5. Complete the Authentication dialog:

Field / Option	Description
Email Address	This displays the service account email specified in the Account tab.
Type	Select the service account's password type (e.g. domain or cloud).
Password	Enter the service account's password.

6. Click Next. The Verification tab is displayed.
7. If you use a 2-step authentication mechanism, a verification code is sent by SMS or email. 
8. Enter the Code within 15 minutes.

If the verification code entered is older than 15 minutes or has been used before, the verification fails, and a new code must be issued.

9. Click Next. The Keys tab is displayed with the generated keys hidden by default.

• • Click on the icon to display a Key.
  • Click on the   icon to copy the Keys to your clipboard and temporarily save them.

9. Click the Finish button to exit the wizard and return to the application list.

Changing an API Application

To change an API Application:

1. From the Available Integrations tab, select your desired API from the available options or choose the Mimecast API 1.0 tile if you created your own custom API.
2. Click on the Edit button. The Details settings tab displays by default.
3. Make any necessary changes. You can click on Details / Notifications in the navigation panel to switch between tabs as required.
4. Click on the Save & Close button. Your changes are applied to the application information displayed.

• Changing settings won't generate a new application key.
• Category and Service Application options cannot be edited.  A new API Application must be created for these options to be changed.

Enabling / Disabling an API Application

To enable/disable an API Application:

1. Click on the Application to be enabled / disabled. A slide-in panel displays.
2. Toggle the Enabled setting on / off.

Alternatively:

1. Click on the ... Icon in the far right corner of the listed applications. A drop-down menu displays.
2. Click on Enable / Disable from the menu, depending on the application's current setting.
3. A popup message displays to confirm your selection.

Deleting an API Application

To delete an API Application:

1. Click on the Application to be deleted. A slide-in panel displays.
2. Click on the Delete button. A popup box displays to confirm the request.
3. Click on the Delete button to proceed.

Alternatively:

1. Click on the ... Icon in the far right corner of the listed application. A drop-down menu is displayed.
2. Click on Delete.

See Also...

• APIs
• Alliance and API Ecosystem
• Detailed API function Calls and Response Codes.