This guide lists the publicly accessible RESTful APIs that can be used to interface with the Mimecast Awareness Training platform.
The following URLs are available:
- https://secure.ataata.us: This is used to access the APIs during development and testing.
- https://secure.ataata.com: This is used to access the APIs in a live production environment.
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:>
- 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.
- 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>
This section lists the sequence of APIs that need to be called (after authenticating and acquiring the access token) for some example tasks.
|Bulk User Upload||Call 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 User||Call PUT /clientapi/version/company/user|
|Delete Single User||Call DELETE /clientapi/version/company/user/:userId|
|Update Single User||Call POST /clientapi/version/company/user|
|List of Existing Users||Call GET /clientapi/version/company/users|
Authentication API for System Access
|Description||Authentication 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|
User Authenticated by the SSO System
|Description||The user has already been authenticated by the SSO system.|
Uploading a Roster File
|Description||Called to upload excel roster file.|
|Input||Use multi-part form upload and key for the file should be ‘roster’.|
|Additional Information||The 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
|Description||Called to get status of the last roster upload.|
Adding an Employee
|Description||Add a new employee into the system.|
Deleting an Employee
|Description||Delete an employee from the system. For URL parameter, specify the User ID or Email.|
|Additional Information||Example: DELETE https://email@example.com|
Updating an Employee
|Description||Update an existing employee.|
|Description||Get a list of current employees in the system.|