Introduction

Mindstep services are organised by functionality. The APIs exposed by all services are organised around the principles of REST. This means they have predictable resource-oriented URLs, use standard HTTP response codes, authentication and verbs, and returns JSON-encoded responses.

Authentication

All Mindstep services use API keys to authenticate requests. At the time of writing there is no self-service mechanism for managing API keys. Your account manager will issue you with a set of keys that can be used to authenticate requests in our sandbox and production environments.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authentication to all endpoints is via bearer auth. This means you need to set the Authorization header appropriately on every request. For example:

Authorization: Bearer m_live_your-production-api-key

Errors

All Mindstep services use conventional HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate succes. Codes in the 4xx range indicate a problem with the request. Codes in the 5xx range indicate a problem on our side. The table below explains some common status codes.

Status code	Name	Description
200	OK	The request was handled successfully.
201	Created	The request successfully created a resource.
400	Bad Request	Something was wrong with the request. For example, the request body was missing a required property.
401	Unauthorized	Missing API key, or invalid API key provided.
403	Forbidden	The provided API key does not have permissions to access the requested resource.
404	Not Found	The requested resource could not be found.
429	Too Many Requests	The provided API key has made too many requests too quickly.
500	Internal Server Error	Something went wrong on Mindstep's end.