API 1.0 Documentation - Authorization

This article contains information on generating required Mimecast API request headers, including date, request ID, app ID, and creating HMAC-SHA1 authorization signatures for secure access.

Overview

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

Prerequisites

• You are Developer, using Mimecast APIs to develop integrations with Mimecast.

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

You can create the Authorization signature by using the following steps:

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, where:
   • {realm} is MC.
   • {accessKey} is the user's Access Key.
   • {Base64 encoded signed Data To Sign} is the result of the calculation made in step 3.

{realm} {accessKey}:{Base64 encoded signed Data To Sign}

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

See Also...

• API 1.0 Documentation