Authentication

Application with a user interface

When developing an application with a user interface you will provide a way for the user to enter their email address and password in order for them login using your application and receive the access key and secret key binding required to authorize API requests.

This page provides an overview of the logic you should implement in your application to get the access key and secret key values required to authorize all requests to the API.

Programatically discover the correct base URL

Mimecast hosts data centers in many regions around the world. The region that a Mimecast account is hosted will dictate the API base URL that should be used for API requests. To prevent confusion the API provides a global function to programatically get the correct base url for any given user.

To use this function you send a request to https://api.mimecast.com/api/login/discover-authentication, for example:

The value of the "api" field in the object in the data array should be used as the base URL for all requests for the given user.

Login to get an access key and secret key binding

Login is the process of exchanging user credentials for an access key and secret key binding. To login, provide user inputs for email address, password, and the password type (either Cloud or Domain). Use these values in a request to /api/login/login. For example,

Strore the accessKey and secretKey values to be used for future requests to the API.

Handle expired access key and secret key bindings

An access key and secret key binding has a time to live. This is defined by the Authentication Cache TTL setting in the user's effective Authentication Profile. If you make a request to the API using an expired binding you will receive 418 status code in response to your request. For exmaple,

On sucess, this will return the same response as the initial login and you will be able to successfully call the API again.

Provide a logout function

Mimecast limits the number of access key and secret key bindings that a user can have. Once the maximum is reached the user will no longer be able to use the API and you will need contact Mimecast support to request that the bindings are cleared. To prevent a build up of bindings the API provides a logout function that will remove the binding from Mimecast so it can no longer be used. To use the logout function you send an authorized request to the /api/login/logout endpoint. For example,

Handle the different user states

Where a login or refresh binding is not successful the status code returned is 401. A reason code is returned in an object in the errors array in the fail array of the response. The table below details expected error responses and the associated reasons. You should ensure that your application handles these responses.