Skip to content

Midaxo Cloud API Overview

The Midaxo Cloud API provides programmatic access to Midaxo's functionality. This page gives you an overview of the API design, authentication methods, and general guidelines for using the API.

API Design

The Midaxo Cloud API follows RESTful principles:

  • Resources are accessed via standard HTTPS requests
  • HTTP methods (GET, POST, PUT, DELETE) determine the operation performed
  • Response format is JSON
  • Standard HTTP response codes indicate the result of each request

Base URL

All API requests should be made to:

Instance URL
Midaxo Cloud EU https://api.app-eu.midaxo.com
Midaxo Cloud US https://api.app-us.midaxo.com

Authentication

Midaxo Cloud REST API uses OAuth2 as the authentication protocol and JWT access token in the Authorization header. The access token is included in the Authorization header solely and without the Bearer keyword:

  • Authorization: eyABCDEFGH...

Machine to Machine Authentication

First, you need to request machine-to-machine credentials from Midaxo Support.

Please provide the following information:

  • Your Midaxo Cloud account/organization name
  • Which workspace(s) you want to have the credentials for. We will provide the API client credentials for each requested workspace.
  • Contact information to share the credentials with.

You will get the client_id and the client_secret values that can be used with the client_credentials flow to authenticate with and get the access token in return.

Auth0 provides good examples in different programming languages how to perform the client_credentials request to get an access token. You can find the examples here.

Here is an example using Python

import http.client

AUTH_DOMAIN = "correct-api-domain-value"
AUDIENCE = "correct-audience-value"
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"

conn = http.client.HTTPSConnection("")
payload = f"grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&audience={AUDIENCE}"
headers = { 'content-type': "application/x-www-form-urlencoded" }
conn.request("POST", "/{AUTH_DOMAIN}/oauth/token", payload, headers)
res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Below are the required info for the authentication for the different Midaxo Cloud instances.

Midaxo Cloud environment Auth domain Auth endpoint Audience
EU auth.app-eu.midaxo.com /oauth/token kappa-appsync-app-api
US auth.app-us.midaxo.com /oauth/token kappa-appsync-app-api

Interactive / User Authentication

If you want to provide access to the data for specific users, then you need to integrate with our interactive authentication. As this is more tightly integrated authentication scheme, please reach out to Midaxo Cloud support and we will work with you.

Rate Limiting

API requests are not currently rate-limited, but this is subject to change. HTTP response 429 will be returned when the rate limit is exceeded.

Pagination

Tip

The Midaxo Cloud API has a 6 MB maximum response size limit for a request. If you encounter errors in your responses, add the pagination query parameters to your request to reduce the response size.

Some of the Midaxo Cloud API endpoints support pagination for their responses. You can add the first query parameter to your request to limit the page size to the value in the first parameter.

  • ?first=10 returns 10 items.
  • ?first=30 returns 30 items.

The paginated endpoints return the top-level paging object that contain the startCursor and endCursor keys.

  • startCursor is an opaque cursor that can be used to request the page returned from this request.
  • endCursor is an opaque cursor that can be used to request the next page.

You can use the cursor values by appending the after query parameter to your API request. The example below for a paginated request shows how to use the cursors with the after query parameter.

Example response for /processes/{processId}/projects?first=2 that returns 2 projects and the paging cursors.

{
  "projects": [{ "...": "..." }],
  "paging": {
    "startCursor": "abcdefg",
    "endCursor": "hjklmnp"
  }
}

You would then make a request /processes/{processId}/projects?first=2&after=hjkmlnp to get the next page with 2 items.

Updated range

The /processes/{processId}/projects endpoint supports additional updatedAfter and updatedBefore query parameters for filtering. You can add the updatedAfter query parameter to your request to limit the query response to only projects updated after the given date-string value. You can add the updatedBefore query parameter to your request to limit the query response to only projects updated before the given date-string value. These two parameters can be used alone or together to limit the project update range for the query.

  • ?updatedAfter=2024-11-24T00:00:00Z returns projects that have been updated after given date.
  • ?updatedBefore=2024-11-26T00:00:00Z returns projects that have been updated before given date.

Note, that these parameters also work without the exact timestamp.

  • ?updatedAfter=2024-11-24 returns projects that have been updated after given date.
  • ?updatedBefore=2024-11-26 returns projects that have been updated before given date.

The example below shows how to use the updated range parameters in conjunction with first parameter in query parameters.

Example response for /processes/{processId}/projects?first=2&updatedAfter=2024-11-24T00:00:00Z&updatedBefore=2024-11-26T00:00:00Z that returns 2 projects within given updated range, and paging cursors.

{
  "projects": [{ "...": "..." }],
  "paging": {
    "startCursor": "abcdefg",
    "endCursor": "hjklmnp"
  }
}

Error Handling

The Midaxo Cloud API uses standard HTTP status codes to indicate success or failure of requests:

  • 2xx: Success
  • 4xx: Client error
  • 5xx: Server error