Overview

• 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 Key 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. 

• Due to the Administration Authentication Profile and its ability to override authentication for any user granted rights by an administrator role, we recommend generating the Access and Secret Keys before adding the user to any administrative role. 

• If Access and Secret Keys need to be generated, the user should first be removed from any administrative role and added back after new keys have been obtained. 

• For the above reasons, we also recommend using an API service account user, rather than generating keys with your normal Mimecast administration accounts. There is no additional licensing needed for service account users. 

• 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 that can be performed within that window as part of the Creating User Association Keys section. 

Steps of Configuration

Accessing Your API Applications

To access your API Applications:

1. Log on to the Administration Console.

2. Navigate to Administration | Services | API and Platform Integrations.

3. Click on the Your Application Integrations 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. Click Add API Application.

2. Fill in the Details section as outlined below:

3. Click Next.

4. Fill in the Settings section as outlined below:

5. Click Next.

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

• Click on the Edit link next to the Details or Settings to return to the relevant page.

• Make your changes and click on the Next button to proceed to the Summary page again.

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

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

Open

8. Copy and paste the Application ID and Application 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 the specific purpose of making API calls, such as a service user account (e.g. svc-siem@domain.tld). The reasons for this recommendation are: 

• Authentication: When generating user association keys, only SMS and two-factor authentication mechanisms are supported, or no two-factor authentication at all. The most common configuration of authentication within Mimecast is an identity provider or SAML assertion. By having a service account user, we 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. 

Prerequisites
Creating a service account user:

Note: 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.

To create a new service account user: 

1. Navigate to Administration | 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.

Creating an API user Authentication Profile:

Application Settings and Authentication Profiles determine how a user, or service account user, can access Mimecast. We recommend creating a new set of both specific for API access and applying this authentication profile based on a group in Mimecast.

To create a Profile Group Containing the Service User:

1. Navigate to Administration | Directories | Profile Groups

2. Click on the + icon next to the Root folder. 

3. Click on the "New Folder".

4. Rename the folder in the Edit Group text box. 

5. Press the enter key.

6. To add the Service User to the group, click Build | Add Email Addresses.

7. Type this Service User's email address into the Group Additions text box. 

8. Click Save and Exit.

To create an Authentication Profile: 

1. Navigate to Administration | Services | Applications | Authentication Profiles 

2. Click New Authentication Profile.

3. Configure using the following settings: 

   1. Description: Enter a description for the profile. 

   2. 2-Step Authentication: Use the dropdown to select SMS, Email, 3rd Party, or None.

   3. Leave all other settings as the default values.

4. Click Save and Exit.

5. Click Go Back. 

To create Application Settings: 

1. Click New Application Settings. 

2. Configure using the following settings: 

   1. Description: Enter a description for the profile. 

   2. Group: Click Lookup and Select the previously created profile group.

   3. Authentication Profile: Click Lookup and Select the previously created authentication profile.

   4. Leave all other settings as the default values 

3. Click Save and Exit.

After completing these steps, any user that is added to the profile group will have the desired 2-Step Authentication steps applied. 

 NOTE: The default Administrator Authentication Profile will override these settings for any user added to an administrator role. If you need to generate new API keys in the future, the service user account should be removed from any administrator role before generating the new keys. Once the keys are generated, the service user account can be re-added to the appropriate administrator role. 

To create the user association 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.Note: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:

6.Click Next. The Verification tab is displayed.

7.If you are using a 2-step authentication mechanism, a verification code is sent to you by SMS or email. 

8.Enter the Code within 15 minutes.Note: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 key to your clipboard.

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

Granting API Service Account User Permissions

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

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

1. Navigate to Administration | 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 to be 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 Administration | 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.

Changing an API Application

To change an API Application:

1. Click on the Application to be changed. A slide-in panel displays.

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.

NOTE: Changing settings won't generate a new application key.

Open

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.

Verification

STEP1: Login to UI >> SYSTEM>> LOGS AND FLOWS COLLECTION STATUS .

STEP 2: >> LOGS AND FLOWS COLLECTION STATUS .

STEP 3: >>Inside SOURCE DEVICE IP, IP will reflect.