Mimecast
Tech Connect / Documentation / API Overview / Authorization

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 GMT

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.