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.