Management API (v1.0.0)

Download OpenAPI specification:Download

Introduction

The Management API offers a set of actions beyond the scope of a single tenant or environment. An environment is a higher-order structure where MATTR VII tenants are hosted in a specific MATTR VII cloud deployment. One tenant must always be a part of exactly one environment. Each environment may include multiple tenants that share hardware resources and environment settings while maintaining authorisation and data isolation.

You can currently use the Management API to create, delete and list tenants, and also to list your enviornments.

Pagination

Most list operations in the API use pagination that can be controlled by a cursor method using the cursor and limit query parameters.

Example on Retrieve List of Credentials

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

The nextCursor is found at the start of each returned range of credential entries and identifies the last object in the list.
The limit determines how many entries are returned in that request, with a maximum value of 1000.

Requesting a page after the last value in the list will return an empty data object.

{
"data": []
}

Not using a query parameter defaults the response to return the first range of credential 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).

bearerAuth

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer
Bearer format	"JWT"

Environments

Retrieve environments

Retrieves a list of all available environments.

Analytic events

ADMIN_ENVIRONMENT_RETRIEVE_LIST_START
ADMIN_ENVIRONMENT_RETRIEVE_LIST_SUCCESS
ADMIN_ENVIRONMENT_RETRIEVE_LIST_FAIL

Authorizations:

bearerAuth

query Parameters

limit	number [ 1 .. 1000 ] Default: 100 Range size of the list, default 100 Example: limit=2
cursor	string Starting point for the list Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://auth.manage.mattr.global/oauth/token?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

200
400

Content type

application/json

{"data": [{"id": "fa605282-0223-4ae0-831d-af368bc39a55",
"name": "MATTR Public Sydney, Australia",
"domain": ".mattr.global",
"authorizationServerDomain": "manage.auth.auth0.com",
"deploymentModel": "public",
"region": {"id": "70bb433a-f0ec-4297-ad76-3b09c71311f3",
"name": "AU01",
"displayName": "Sydney, Australia"
}
}
],
"nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Tenants

Retrieve tenants

Retrieves a list of all available tenants. If you haven't created any tenants, the response will include an empty array.

Analytic events

TENANT_RETRIEVE_LIST_START
TENANT_RETRIEVE_LIST_SUCCESS
TENANT_RETRIEVE_LIST_FAIL

Authorizations:

bearerAuth

query Parameters

limit	number [ 1 .. 1000 ] Default: 100 Range size of the list, default 100 Example: limit=2
cursor	string Starting point for the list Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://manage.mattr.global/v1/tenants?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

200
400

Content type

application/json

{"data": [{"id": "86cb97a9-5e80-4ed7-af13-a170752bb1ea",
"name": "My Tenant",
"subdomain": "my-tenant.vii.mattr.global",
"environment": {"id": "fa605282-0223-4ae0-831d-af368bc39a55",
"name": "MATTR Public Sydney, Australia",
"domain": ".mattr.global",
"authorizationServerDomain": "manage.auth.auth0.com",
"deploymentModel": "public",
"region": {"id": "70bb433a-f0ec-4297-ad76-3b09c71311f3",
"name": "AU01",
"displayName": "Sydney, Australia"
}
}
}
],
"nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Create tenant

Creates a new tenant in the requested environment.

Analytic events

TENANT_CREATE_START
TENANT_CREATE_SUCCESS
TENANT_CREATE_FAIL

Authorizations:

bearerAuth

Request Body schema: application/json

name	string Friendly and/or meaningful name for your new tenant.
subdomain required	string Subdomain for your tenant within requested environment. Only lower case alphanumeric characters (a-z, 0-9) and hyphens are allowed.
environmentId required	string Unique identifier of the environment where you want to create your tenant. This can be obtaining when retrieving environments.

Responses

Request samples

Content type

application/json

{"name": "My Tenant",
"subdomain": "my-tenant",
"environmentId": "84ca6f53-5405-4413-a6ad-848b781807e7"
}

Response samples

201
400

Content type

application/json

{"id": "86cb97a9-5e80-4ed7-af13-a170752bb1ea",
"name": "My Tenant",
"subdomain": "my-tenant.vii.mattr.global",
"environment": {"id": "fa605282-0223-4ae0-831d-af368bc39a55",
"name": "MATTR Public Sydney, Australia",
"domain": ".mattr.global",
"authorizationServerDomain": "manage.auth.auth0.com",
"deploymentModel": "public",
"region": {"id": "70bb433a-f0ec-4297-ad76-3b09c71311f3",
"name": "AU01",
"displayName": "Sydney, Australia"
}
},
"client": {"clientId": "suC7IhmDIawnlqBlEOuIqBWoqppcdI5",
"clientSecret": "QmtShBH3mkO05ra91dNO-YyPwPbfs1iokh57IgqhzVWTAZlolCdeAGYOG2kz1"
}
}

Retrieve tenant

Retrieves a tenant by its ID.

Analytic events

TENANT_RETRIEVE_START
TENANT_RETRIEVE_SUCCESS
TENANT_RETRIEVE_FAIL

Authorizations:

bearerAuth

path Parameters

tenantId

required

string <uuid>

Unique ID of the tenant to retrieve.

Responses

Request samples

curl -i -X GET \
  https://manage.mattr.global/v1/tenants/:tenantId \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

200
400

Content type

application/json

{"id": "86cb97a9-5e80-4ed7-af13-a170752bb1ea",
"name": "My Tenant",
"subdomain": "my-tenant.vii.mattr.global",
"environment": {"id": "fa605282-0223-4ae0-831d-af368bc39a55",
"name": "MATTR Public Sydney, Australia",
"domain": ".mattr.global",
"authorizationServerDomain": "manage.auth.auth0.com",
"deploymentModel": "public",
"region": {"id": "70bb433a-f0ec-4297-ad76-3b09c71311f3",
"name": "AU01",
"displayName": "Sydney, Australia"
}
}
}

Delete tenant

Deletes a tenant by its ID.

Analytic events

TENANT_DELETE_START
TENANT_DELETE_SUCCESS
TENANT_DELETE_FAIL

Authorizations:

bearerAuth

path Parameters

tenantId

required

string <uuid>

Unique ID of the tenant to delete.

Responses

Request samples

curl -i -X DELETE \
  https://manage.mattr.global/v1/tenants/:tenantId \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

400

Content type

application/json

{"code": "string",
"message": "string",
"details": [{"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}

Retrieve clients

Retrieves a list of clients authorised to interact with the requested tenant.

Analytic events

TENANT_CLIENT_RETRIEVE_LIST_START
TENANT_CLIENT_RETRIEVE_LIST_SUCCESS
TENANT_CLIENT_RETRIEVE_LIST_FAIL

Authorizations:

bearerAuth

path Parameters

tenantId

required

string <uuid>

Unique ID of the tenant to retrieve clients for.

query Parameters

limit	number [ 1 .. 1000 ] Default: 100 Range size of the list, default 100 Example: limit=2
cursor	string Starting point for the list Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://manage.mattr.global/v1/tenants/:tenantId/clients?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

200
400

Content type

application/json

{"data": [{"clientId": "suC7IhmDIawnlqBlEOuIqBWoqppcdI5"
}
],
"nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Security

Create API Auth Token

Returns an API access token specific to the Management API. This token must then be used as an authorization header for all requests to protected endpoints (this is required for the majority of operations).

Request Body schema: application/json

client_id required	string Use the `client_id` value provided for authenticating with the Management API authentication provider as part of your on-boarding.
client_secret required	string Use the `client_secret` value provided for authenticating with the Management API authentication provider as part of your on-boarding.
audience required	string Use the `audience` value provided as part of your on-boarding for the Management API.
grant_type required	string Use `client_credentials`.

Responses

Request samples

Content type

application/json

{"client_id": "htf792W4p4MedZbnoWAs51EfqUt4d2",
"client_secret": "d3fYDX7FjPg1D1h2viARXsolPByQ9vMfg8LHylBy8F4s5KJLB4HhHGOxxqJnSj3G",
"audience": "https://my-tenant.vii.mattr.global",
"grant_type": "client_credentials"
}

Response samples

200
401

Content type

application/json

{"access_token": "s2dgbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6s2dcaEROemRDf5gbRVEwTTVSVFE0TmtZME9UZzVNVEpDTlVJNFJqRTBPREExTmpZMk1qazFPQSJ9",
"expires_in": 86400,
"token_type": "Bearer"
}