Mimecast Awareness Training: Public APIs

Document created by user.AndtBm6kql Employee on Apr 16, 2019Last modified by user.oxriBaJeN4 on May 3, 2019
Version 24Show Document
  • View in full screen mode

This guide lists the publicly accessible RESTful APIs that can be used to interface with the Mimecast Awareness Training platform.

 

Base URLs

 

The following URLs are available:

 

Authentication

 

Mimecast Awareness Training uses JSON web tokens (https://jwt.io/) an open industry standard for authenticating API access. API requests can be made on behalf of a user that should be provisioned in the Mimecast Awareness Training platform. The required steps to ensure authentication and subsequent communication are:>

  1. Call authenticate API /api/core/clientauthenticate. If the authentication is successful, the Mimecast Awareness Training platform returns a signed JWT in the response.
    The token expires in one hour.
  2. Call the other APIs depending upon the workflow passing in the JWT (acquired in step 1) as a bearer in the HTTP Authorization header as: Bearer <JWT Token>

 

Workflow Sequences

 

This section lists the sequence of APIs that need to be called (after authenticating and acquiring the access token) for some example tasks.

TaskAPI Call
Bulk User UploadCall POST /clientapi/version/company/roster to upload the excel file that contains the users to be imported. Users that already exists in the system (identified by their email address) are ignored. Users are added into the database through a background process, and depending upon the number of users and system load, the upload process can take some time.
Call GET /clientapi/version/company/roster to poll for completion status.
Add Single UserCall PUT /clientapi/version/company/user
Delete Single UserCall DELETE /clientapi/version/company/user/:userId
Update Single UserCall POST /clientapi/version/company/user
List of Existing UsersCall GET /clientapi/version/company/users

 

API Descriptions

 

Authentication API for System Access

 

URL/api/core/clientauthenticate
MethodPOST
DescriptionAuthentication API for system access. This is for a user with special privileges and dedicated API access. This differs from other provisioned users. Parameters required for this API can be configured / retrieved from the Web Admin dashboard by navigating to: Settings -> Company Settings -> Enable/Disable External API access
Input{
   “key”: <retrieved admin dashboard>
   “secret”: <configured in admin dashboard>
}
Output{
    “token”: <JWT token that needs to be passed in subsequent requests>
}
Additional Information

 

User Authenticated by the SSO System

 

URL/api/core/ssoauthenticate [DEPRECATED]
MethodPOST
DescriptionThe user has already been authenticated by the SSO system.
Input{
    “key”: <key provided by Ataata>
}
Output{
    “token”: <JWT token that needs to be passed in subsequent requests>
}
Additional Information

 

Uploading a Roster File

 

URL/clientapi/v0/company/roster
MethodPOST
DescriptionCalled to upload excel roster file.
InputUse multi-part form upload and key for the file should be ‘roster’.
Output{
    "message": <indication to user>,
    “duration”: <expected completion duration in minutes>
}
Additional InformationThe file is checked to ensure it is correctly formatted before being uploaded. To prevent any errors, use the template that can be downloaded from the dashboard.

 

Requesting the Status of the Last Roster Upload

 

URL/clientapi/v0/company/roster (GET)
MethodGET
DescriptionCalled to get status of the last roster upload.
Input>None
Output{
    “uploadTs”: <last file upload timestamp>
    "status": ‘DONE’|’PENDING’,
    "lastUploadStatus": {  // NOTE: This is optional field
        "parsed": <records parsed>,
        "duplicate": <duplicate records that were skipped>,
        "added": <records added>,
        "errors": <records that were skipped due to error>
        "details": [
            <Array of items giving reason for not adding>
            {
                        "Email": <Email address associated with the record>
                        "Reason": <Reason for not adding>
            },
            {   <More items>
          }
        ]
    }
}
Additional Information

 

Adding an Employee

 

URL/clientapi/v0/company/user (PUT)
MethodPUT
DescriptionAdd a new employee into the system.
Input{
    "name": "John Doe",
    "email": "jdoe@ataata.com",
    "department": "Marketing",
    "role": "DASH-NONE",
    "empId": <some string>, // optional field - UI should indicate as such - only needed for some companies
    “cfields”: { // optional - only present if company has defined custom fields
        <“Cf1”: <value1>,
        <“Cf2”: <value2>
         <more values>
}
Output{
    “success”:true|false,
    “message”:<error message if result is false>
}
Additional Information

 

Deleting an Employee

 

URL/clientapi/v0/company/user/:userId_or_Email (DELETE)
MethodDELETE
DescriptionDelete an employee from the system. For URL parameter, specify the User ID or Email.
InputNone
Output{
    “success”:true|false,
    “message”:<error message if result is false>
}
Additional InformationExample: DELETE https://secure.ataata.com/clientapi/v0/company/user/xyz@gmail.com

 

Updating an Employee

 

URL/clientapi/v0/company/user (POST)
MethodPOST
DescriptionUpdate an existing employee.
Input{
    “email”: <current email>,
    “updateInfo”: { // optional fields - only need to provide changes
       “makeActive”:true, <used to make an inactive employee active again>
       "name": <any change in name>,
       "email": <new email address>, // email needs to be removed if not changed
       “department”: <new department>,
       “empId”: <new employee id>,
       “cfields”: { // optional - only present if company has defined custom fields
       “Cf1”: <value1>,
       “Cf2”: <value2>
       <more values>
      }
    }
}
Output{
    “success”:true|false,
    “message”:<error message if result is false>
}
Additional Information

 

Listing Employees

 

URL/clientapi/v0/company/users (GET)
MethodGET
DescriptionGet a list of current employees in the system.
InputNone
Output[
  {
    "name": <User’s name>,
    "role": <current role>,
    "department": <User’s dept>,
    "userId": <Internal userId>,
    "email": <User’s email address>,
    “empId”: <valid employee Id or null>,
    “riskScore”: null, <for future use>,
    “flags”: {}|{ <additional user properties - see Notes>},
    “cfields”: <company specific custom fields>
  }
  <Array of as many users>
]
Additional Information
  • flags
    • 'bounce': true|false: Email address has been bounced.
    • 'inactive': If the user is inactive. This is only applicable if your company setting dictates that users should be marked inactive upon deletion.

Attachments

    Outcomes