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:

...

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:

...

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.

...

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.

...