This API provides endpoints that will aide in the automation and securing of data exchanged between Critical Mix and our clients. We plan to continually add new endpoints as we identify additional needs or features that could benefit both Critical Mix and our clients. While the API will continue to grow, we are committed to doing so only in a non-breaking fashion whenever possible.
How to Use our API
The production URL for this API is:
We also offer a sandbox or testing URL:
All requests must be made over HTTPS. All data is sent and received as JSON. When making requests, you receive the response data as JSON by properly setting the
Accept header to
application/json. Requests which contain a body must send the data as JSON by also setting the proper
Content-Type header to
All endpoints provided by this API require you to provide a valid access token within a custom header,
CM-Authorization. The only exception is the endpoint
/security/authenticate which is used to retrieve an access token.
Critical Mix will provide you with a username and password as a part of the on-boarding process for the use of this API. The username and password are used in calls to
/security/authenticate to generate a security token. The access token will remain valid indefinitely. Access tokens are only invalidated if they are suspected to be compromised. Multiple calls to
/security/authenticate will result in the same security token being returned until that token is manually invalidated.
Our recommended approach is to implement authentication for calls to any endpoint in the following manner:
- If your code does not have a cached authentication token, call
/security/authenticateto retrieve a token
- Save the token in a local memory cache for re-use
- Call the desired endpoint using the cached security token
- If your request gets an authentication error (described below) then make a new call to
/security/authenticateto get a new token
- Update your local cache with the new token
- Retry calling the desired endpoint with the new token
This approach minimizes the potential of your username/password becoming compromised because it is not sent with every request. The token can be invalidated and a new token easily retrieved in case of any security concerns.
Alternative approaches include:
- Call the
/security/authenticateendpoint to get the token before every call to any other endpoint. This is acceptable, but increases the risk that your username and password become compromised.
- Retrieve your security token once and implement it in your code. If it becomes necessary to invalidate the token, or if you begin receiving authentication errors (described below), you would need to manually retrieve a new token and update your code.
Currently, this API does NOT return the appropriate Status codes (
401: Unauthorized or
403: Forbidden ) for authentication and authorization errors. Instead, a
500: Internal Server Error is returned. Additionally, a JSON string which describes the error is included in the response.
Requests to the various endpoints should use the appropriate specified verbs (HTTP Methods) as listed in the endpoint documentation.
If the request requires a body, the format of that body should always be well-formed JSON. The
Content-Type header should be set to
application\json when a JSON body is included with the request.
If an endpoint requires authentication, then the appropriate headers should be included, as detailed under Authentication.
HTTP Status Codes
Successful calls to the endpoints will return an appropriate HTTP Status Code from the following list:
|HTTP Status Code||Usage|
All successful calls
Success Response Headers
MIME type of the response body
Success Response Data
A response body will also be included in JSON format if one is specified for the endpoint. Check the documentation for each endpoint for details of what is included in each response.
Success Response Examples
Check the documentation for each endpoint for examples of the success response.
HTTP Status Codes
Calls to the endpoints which result in an error, or which are not able to successfully create or update the specified resource will return an appropriate HTTP Status Code from the following list:
|HTTP Status Code||Usage|
400: Bad Request
|The expected JSON body is missing or invalid, or the request is missing required parameters|
404: Not Found
|A non-existent resource has been requested, or data in the request body specifies a missing or invalid object.|
|A request has been made to set data in a way that conflicts with a previous request|
500: Internal Server Error
|Authentication error or any other error not covered by a different status code|
Error Response Headers
|MIME type of the response body|
Error Response Data
|timestamp||number||Unix timestamp of when the response was generated|
|status||number||The same value returned as the HTTP Status Code|
|error||string||Description of the status code|
|exception||string||Details of the exception thrown within the API, if any.|
|message||string||The user-friendly text describing the error, or "No message available"|
|path||string||Path of the endpoint that generated the response|
Error Response Examples