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.
Management API credentials
The Management API uses its own machine-to-machine (M2M) client credentials, made up of a client ID and a client secret. MATTR issues these credentials to your organization on request. They are designed for your own systems to call, such as a provisioning service or a deployment pipeline, so that platform management tasks can run without a person signing in.
Typical uses include:
- Creating a new tenant each time you onboard a new customer, program or business unit.
- Creating tenant clients and storing their secrets directly in your own secrets vault.
- Assigning roles to tenant clients as part of an automated workflow.
To request Management API credentials, contact us.
How Management API credentials differ from other access
MATTR VII has three kinds of access that are easy to confuse:
| Portal user | Management API credentials | Tenant client credentials | |
|---|---|---|---|
| Represents | A person | A system acting on behalf of your organization | A system acting within a single tenant |
| How you get it | Sign up to the Portal, or be invited to a tenant | Issued by MATTR on request | Created in the Portal or with the Management API |
| What it calls | The Portal | The Management API (for example https://manage.au01.mattr.global) | The tenant's own APIs, for example to issue or verify credentials |
| Tenant access | Tenants the person created or was invited to | Tenants created with these credentials, plus any tenants MATTR assigns to them | Only the tenant the client belongs to |
Management API credentials are not linked to any Portal user account. If you name a contact person when you request them, that person is only who MATTR contacts about the credentials. The credentials do not act as that person and do not inherit the tenants that person can see in the Portal.
Tenant client credentials cannot be used to call the Management API. To give a system access to a tenant's own APIs, use the Management API to create a tenant client and give that system the new client's credentials.
Tenant access
Management API credentials can only manage the tenants they have access to:
- Tenants created with the credentials: When you create a tenant with your Management API credentials, they are automatically assigned the Admin role on that tenant. The tenant is returned when you retrieve all tenants and you can manage it straight away.
- Tenants created any other way: Tenants created in the Portal, or with a different set of
Management API credentials, are not accessible to your credentials. They are not returned when
you retrieve all tenants, and requests that reference them return a
404 Not Foundresponse. The platform has no record that these tenants belong to the same organization as your credentials.
For example, suppose your team created a staging tenant and a production tenant in the Portal while evaluating MATTR VII, and later requested Management API credentials to automate client creation. Calling retrieve all tenants with the new credentials returns an empty list, because neither tenant was created with them.
Tenant invitations are for Portal users only, so a Portal user cannot invite Management API credentials to a tenant. Instead, MATTR assigns existing tenants to your credentials for you. To request this, raise a support request through the MATTR Service Desk or contact us and include:
- The client ID of your Management API credentials. Never share the client secret.
- The ID or subdomain of each tenant to assign, and the environment it is in.
- The role to assign on each tenant, for example Admin.
If you plan to manage tenants with the Management API, create them with your Management API credentials from the start. They are then available to your credentials straight away, without a support request.
Getting started
The base URL you use for Management API requests depends on your environment and region, and on
whether you are on a Regional Cloud or Dedicated Cloud deployment. The examples below use the
public au01 (Sydney) region. Adjust the URLs to match your own environment. For more
information, see Deployment
Models. If you are unsure
which URL applies to you, contact us.
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:
POST https://auth.manage.mattr.global/oauth/tokenThe authentication domain does not include a region code, unlike the Management API base URL and
the audience value. Use auth.manage.mattr.global for all regions. Region specific variations
such as auth.manage.au01.mattr.global do not exist.
{
"client_id": "F5qae****************************",
"client_secret": "Wzc8J**********************************************************",
"audience": "https://manage.au01.mattr.global",
"grant_type": "client_credentials"
}client_id: Replace with theclient_idvalue from your management API client credentials.client_secret: Replace with theclient_secretvalue from your management API client credentials.audience: Always usehttps://manage.au01.mattr.globalas a static value, regardless of your specific management API client credentials.grant_type: Always useclient_credentialsas 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
{
"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 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:
POST https://manage.au01.mattr.global/v1/tenants{
"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 theidvalue from the response as theenvironmentId.
Response
{
"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.au01.mattr.global",
"deploymentModel": "public",
"authorizationServerDomain": "auth.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 thesubdomainvalue provided in the request.environment: Indicates data for the environment in which the new tenant was created.client: Indicates theclientIdandclientSecretfor 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.
Inviting users to a tenant is only supported for Portal users that are members of the tenant. The machine-to-machine (M2M) client used to access the Management API cannot invite users. Calling the invite a tenant member endpoint with an M2M client token returns a 404 Resource Not Found response, even when the client holds an admin role.
A tenant created with an M2M client has no Portal members, so no one can be invited to it until a Portal user is a member. To manage tenant membership, create the tenant from the MATTR Portal instead. The Portal user that creates the tenant becomes a member automatically and can then invite additional users, either from the Portal UI or by calling the invitation endpoint with that Portal user's access token.
How would you rate this page?
Last updated on