MATTR VII Management API Overview

The MATTR VII Management API enables administrators to perform actions that span across multiple tenants.

The MATTR VII Management API enables administrators to perform actions that span across multiple tenants. It provides capabilities for creating, updating, and managing tenants, as well as configuring access controls, defining who can access each tenant, with what roles, and which permissions. This API is essential for orchestrating large-scale deployments and maintaining centralized oversight of your digital trust infrastructure.

OpenAPI Specifications

Download the complete OpenAPI specifications for the MATTR VII Management API:

Management API

Getting Started

Obtain an access token

Before you can make any API requests to manage your MATTR VII tenants, you must complete authentication by obtaining a management API access token from our authentication provider.

Use your management API client credentials to make a request of the following structure:

Request

POST https://auth.manage.au01.mattr.global/oauth/token

Request body

{
    "client_id": "F5qae****************************",
    "client_secret": "Wzc8J**********************************************************",
    "audience": "https://manage.au01.mattr.global",
    "grant_type": "client_credentials"
}

client_id : Replace with the client_id value from your management API client credentials.
client_secret : Replace with the client_secret value from your management API client credentials.
audience : Always use https://manage.au01.mattr.global as a static value, regardless of your specific management API client credentials.
grant_type : Always use client_credentials as a static value, regardless of your specific management API client credentials.

These are not the same client_id and client_secret you were provided for accessing other MATTR VII APIs, but rather unique credentials for accessing the Management APIs. If you have not received these credentials or have any questions, please contact us before proceeding.

Response

Response body

{
    "access_token": "eyJhb********************************************************************", 
    "expires_in": 14400,
    "token_type": "Bearer"
}

The returned access_token must be used as a bearer token for all subsequent requests to any of the protected MATTR VII Management API endpoints.

Construct the request

Construct an API request using the selected endpoint path and the specific region value for your tenant. Use the following template to structure the request:

Request template

{method} https://manage.{region}.mattr.global/{path}

For example, a request to retrieve all tenants in the au01 region should be constructed as follows:

Request example

GET https://manage.au01.mattr.global/v1/tenants

If the operation has a request body you should structure it too, based on the details provided in the API Reference or relevant tutorials.

Whatever tool or language you are using to make the request, make sure you include the access_token in the request header when making requests to protected endpoints. Refer to the API Reference for request samples.

Handle the response

The endpoint would respond with a standard HTTP status code and a response body. These differ between endpoints and are detailed in the API Reference.

You can now adjust your implementation to handle these responses to achieve the desired outcome.

Concepts

Pagination

Most list operations in the API enable cursor pagination using the cursor and limit query parameters:

Example on retrieve all tenants

GET https://manage.au01.mattr.global/v1/tenants
?limit=100
&cursor=Y3JlYXRlZEF0PTIwMjAtMTAtMDhUMjMlM0ExMyUzQTE3Ljg5NtZGUxZWEyNzQ4MWI4

limit: determines how many entries are returned in that request, with a maximum value of 1000.
cursor: sets the location in the retrieved list to get the next batch of entries from. This is based on the returned nextCursor, found at the beginning of each returned range and identifies the last object in the list.

Requesting an entry after the last list value will return an empty data object:

{
"data": []
}

Not providing a query parameter defaults the response to return the first range of entries with a limit of 100.

Authorization

The Management API is a separate set of APIs to MATTR VII. It uses machine-to-machine authentication through its own credentials, which are different from your MATTR VII client credentials.

As part of onboarding you will be provided with the required details to make a call to a dedicated management API authorization provider and receive a bearer token.

This token is then used in an authorization header on all calls identified as requiring bearerAuth (this is required for the majority of management operations).

Rate limiting

To ensure platform stability and consistent resource allocation, API requests are subject to rate limiting. This helps protect the service from excessive usage patterns and ensures consistent performance for all users.

Every response from the MATTR VII Management API includes the following rate limit headers:

x-ratelimit-limit: Maximum requests allowed in time window.
x-ratelimit-remaining: Requests remaining in current window.
x-ratelimit-reset: Timestamp when the window resets.

If you exceed the rate limit, the API will return a 429 Too Many Requests response, and you should pause further requests until the rate limit resets:

Rate limit exceeded response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
x-ratelimit-limit: 10
x-ratelimit-remaining: 0
x-ratelimit-reset: 1768791002

{
  "message": "Too many requests, please try again later."
}

If you're consistently hitting rate limits or believe your use case requires adjusted limits, please contact our support team to discuss your requirements.

Previous versions

This is the latest version of the MATTR VII Management API. Refer to the MATTR VII Changelog for links to previous versions.

MATTR VII Management API Overview

On this page