light-mode-image
Learn
Management API

Management API

Overview

The Management API offers a set of actions to assist system admins to manage the MATTR VII tenants they own. These APIs provide programmatic access to common platform management tasks, including:

  • Retrieving available environments.
  • Creating and managing tenants.
  • Creating and managing clients for accessing tenants.
  • Managing Role Based Access Control (RBAC) for users and clients interacting with tenants.

Similar capabilities are available via the MATTR Portal.

The Management APIs use machine-to-machine authentication through its own credentials, which are different from the client credentials used to access specific MATTR VII tenants.

Getting started

Obtaining a Management API 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": "F5qaeLDdbvnU9zhA0j4eHUGCHwC1bKtt",
    "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 the any of the MATTR VII Management API endpoints, including the next step to create a new tenant.

Creating a tenant

Use the returned access_token must be used as a bearer token for all requests to the Management API in the next steps to make a request of the following structure to create a new tenant:

Request
POST https://manage.au01.mattr.global/v1/tenants
Request body
{
    "name": "My first tenant",
    "subdomain": "my-first-tenant",
    "environmentId": "fa605282-0223-4ae0-831d-af368bc39a55"
}
  • name : The name that will be used to identify this tenant.
  • subdomain : The subdomain that will be used to access this tenant.
  • environmentId : The unique identifier of the environment where the new tenant will be created. You can make a request to retrieve all environments you have access to and use the id value from the response as the environmentId.

Response

Response body
{
    "id": "6facbcef-66cd-4a06-89e3-e44a4fc12000", 
    "name": "My first tenant", 
    "subdomain": "my-first-tenant.vii.au01.mattr.global",
    "environment": { 
        "id": "fa605282-0223-4ae0-831d-af368bc39a55",
        "name": "Public Australia Sydney",
        "domain": "vii.a01.mattr.global",
        "deploymentModel": "public",
        "authorizationServerDomain": "auth.manage.au01.mattr.global",
        "region": {
            "id": "0fd6ce12-a983-41d0-aca8-03e1bb6f6000",
            "name": "au01",
            "displayName": "Sydney, Australia"
        }
    },
    "client": { 
        "clientId": "MjQx108p***************FlwJQjy",
        "clientSecret": "NanfSkVr**********************PfD3zJ"
    }
}
  • id : Globally unique tenant identifier.
  • name : As provided in the request.
  • subdomain : The tenant URL, constructed with the subdomain value provided in the request.
  • environment : Indicates data for the environment in which the new tenant was created.
  • client : Indicates the clientId and clientSecret for the default client created for this tenant. This client is assigned an Admin role by default, meaning it has access to all endpoints in the tenant.

Once the tenant is created you can interact with it as detailed in the Portal getting started guide.

How would you rate this page?