API 2.0 Overview API 1.0 to 2.0 Migration Guide What's New
Action Usecase Alerting Usecase Analysis and Response API's Building Search Queries Configuration Backup Restore and Export APIs Enrichment Usecase Groups Usecase Mimecast API In Power BI Secure Email Gateway SIEM Tutorial CG SIEM Tutorial CI SIEM Batch CG Guidelines SIEM Batch CI Guidelines
API 2.0 Reference API 1.0 Reference
Technology Partners
Become a Partner

Authorization

All requests to the Mimecast API (except login and discover authentication) must be authorized and include the following request headers

  • x-mc-date - the date and time of the request,
  • x-mc-req-id - a unique request id,
  • x-mc-app-id - your Mimecast Application ID and
  • Authorization - a realm followed by a signature
    • A signature includes a user specific Access Key and a combination of unique values signed with a user specific Secret Key using HMAC-SHA1 encryption.

This allows Mimecast to determine the identity of the requesting user, the identity of the requesting application, the user's authentication status, and the user's privileges.

Date / Time (x-mc-date)

The x-mc-date header must be created in the following format:

Tue, 24 Nov 2015 12:50:11 UTC

Request ID (x-mc-req-id)

The x-mc-req-id header is a Globally Unique Identifier (GUID). Most frameworks have ways to generate these easily. An example value is:

8578FCFC-A305-4D9A-99CB-F4D5ECEFE297

Application ID (x-mc-app-id)

The value of the application id provided when you registered your application.

Creating the Authorization signature

To create the signature:

  1. Concatenate the following values: 'x-mc-date' + ':' + 'x-mc-req-id' + ':' + '{uri} + ':' + {application key}' where {uri} is the actual uri of the endpoint the request is sent to and {application key} is the application key value provided when you registered your application. This creates the Data To Sign.
  2. Use the user's base64 decoded Secret Key to calculate the hash-based message authentication code (HMAC) of the Data To Sign using the HMAC-SHA1 algorithm.
  3. Base64 encode the result of the signed Data to Sign.
  4. Add an Authorization header to your request containing the following elements:
    {realm} {accessKey}:{Base64 encoded signed Data To Sign}

    Where:

    1. {realm} is MC
    2. {accessKey} is the user's Access Key.
    3. {Base64 encoded signed Data To Sign} is the result of the calculation made in step 3.

Sample code demonstrating how to contruct the Authorization header is provided on each endpoint reference guide.

Back to Top