Manage tenants

This tutorial will introduce you to available tenant management capabilities:

• Create a tenant

• Delete a tenant

• List Tenants

• Retrieve your client ID

These capabilities are also available via our Self service portal.

Before you begin

Make sure you have obtained an access token before making any API requests.

Create a tenant

Make the following request to create a new tenant in your environment:

Request

1POST https://manage.mattr.global/v1/tenants

1{
2  "name": "My First Tenant",
3  "subdomain": "tenants-test-subdomain",
4  "environmentId": "4b69a1d6-1f4d-4df7-a149-c4bb89c5d000"
5}

• name: The name that will be used to identify this tenant.

• subdomain: The subdomain that will be used to access this tenant. Only lower case alphanumeric characters (a-z, 0-9) and hyphens are allowed.

• environmentId: This identifier will be provided to you by MATTR as part of onboarding to the Management API capability. Contact us if you did not receive it.

Response

1{
2    "id": "6facbcef-66cd-4a06-89e3-e44a4fc12000",
3    "name": "My First Tenant",
4    "subdomain": "tenant-test-subdomain.vii.mattr.global",
5    "environment": {
6        "id": "4b69a1d6-1f4d-4df7-a149-c4bb89c5d000",
7        "name": "Public Australia Sydney",
8        "domain": "vii.mattr,global",
9        "deploymentModel": "public",
10        "authorizationServerDomain": "auth.manage.mattr.global",
11        "region": {
12            "id": "0fd6ce12-a983-41d0-aca8-03e1bb6f6000",
13            "name": "au01",
14            "displayName": "Sydney, Australia"
15        }
16    },
17    "client": {
18        "clientId": "MjQx108p***************FlwJQjy",
19        "clientSecret": "NanfSkVr**********************PfD3zJ"
20    }
21}

• id: Globally unique tenant identifier.

• name: The name you set in the request.

• subdomain: The tenant URL, constructed with the subdomain you set in the request.

• environment: Indicates environment data.

• client: Indicates the tenant clientId and clientSecret. Make sure you store these securely for future authentication. The clientSecret cannot be retrieved again after this point.

Delete a tenant

The Management API provides the ability to soft-delete a tenant. The tenant is no longer available through the Management API, but its data is not removed and the tenant itself remains accessible through authentication with its original client ID and secret.

If you wish to permanently delete your tenant and its data, please contact us.

Make the following request to soft-delete a tenant based on its identifier:

Request

1DELETE https://manage.mattr.global/v1/tenants/TENANT_ID

• TENANT_ID: Replace with the tenant identifier obtained when it was created.

Response

1Status Code: 204 No Content

The 204 response indicates a succesful deletion.

List tenants

Make the following request to retrieve a list of tenants in your environment:

Request

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

Response

1{
2    "data": [
3        {
4            "id": "6facbcef-66cd-4a06-89e3-e44a4fc12000",
5            "name": "My First Tenant",
6            "subdomain": "tenant-test-subdomain.vii.mattr.global",
7            "environment": {
8                "id": "4b69a1d6-1f4d-4df7-a149-c4bb89c5d000",
9                "name": "Public Australia Sydney",
10                "domain": "vii.mattr,global",
11                "deploymentModel": "public",
12                "authorizationServerDomain": "auth.manage.mattr.global",
13                "region": {
14                    "id": "0fd6ce12-a983-41d0-aca8-03e1bb6f6000",
15                    "name": "au01",
16                    "displayName": "Sydney, Australia"
17                }
18            }
19        }
20    ]
21}

Success is indicated by a returned 200 HTTP status code. If you haven’t created any tenants yet, this request will return an empty array.

By default you only have access to tenants that you have created using your Management API credentials. If you wish to access additional tenants, please contact us.

Retrieve your client ID

To access your tenant, you will need a clientId and a clientSecret. Make the following request to retrieve the clientId for a given tenant:

Request

1GET https://manage.mattr.global/v1/tenants/TENANT_ID/clients

• TENANT_ID: Replace with the tenant identifier obtained when it was created.

Response

1{
2    "clientId": "MjQx108p***************FlwJQjy"
3}

The tenant's clientSecret is only available when initially creating a tenant and cannot be retrieved at a later point.

What's next?

After creating your tenant and recording its credentials, you get started with using it.