Learn

Management API (v1.13.0)

Download OpenAPI specification:Download

E-mail: support@mattr.global

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 authorization and data isolation.

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

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

  • ENVIRONMENT_RETRIEVE_LIST_START
  • ENVIRONMENT_RETRIEVE_LIST_SUCCESS
  • ENVIRONMENT_RETRIEVE_LIST_FAIL
SecuritybearerAuth
Request
query Parameters
limit
number [ 1 .. 1000 ]
Default: 100

Range size of returned list.

Example: limit=2
cursor
string

Starting point for the list of entries.

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
Responses
200

A list of environments

400

Bad Request. The request was malformed or missing required parameters.

401

Unauthorized. The client is not recognized by authorization server.

403

Forbidden. The client is recognized by authorization server but is not allowed to access this resource.

500

Internal Server Error. An unexpected error occurred.

get/v1/environments
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "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
    • 



SecuritybearerAuth 
Request 
query Parameters
limit
number  [ 1 .. 1000 ] 
 Default:  100
Range size of returned list.


 
 Example:  limit=2
cursor
string
Starting point for the list of entries.


 
 Example:  cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
Responses 
200
A list of tenants


400
Bad Request. The request was malformed or missing required parameters.


401
Unauthorized. The client is not recognized by authorization server.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


500
Internal Server Error. An unexpected error occurred.


get/v1/tenants
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}
Create tenant
Creates a new tenant in the requested environment.


Analytic events


    

  • TENANT_CREATE_START
    • 

  • TENANT_CREATE_SUCCESS
    • 

  • TENANT_CREATE_FAIL
    • 



SecuritybearerAuth 
Request 
Request Body schema: application/json
required
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 obtained by retrieving environments.


 
Responses 
201
Tenant created


400
Bad Request


401
Unauthorized. The client is not recognized by authorization server.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


500
Internal Server Error. An unexpected error occurred.


503
Service Unavailable. The server is temporarily unavailable to handle requests.


post/v1/tenants
Request samples 
application/json
{
  • "name": "My Tenant",
  • "subdomain": "my-tenant",
  • "environmentId": "84ca6f53-5405-4413-a6ad-848b781807e7"
}
Response samples 
application/json
{
  • "id": "86cb97a9-5e80-4ed7-af13-a170752bb1ea",
  • "name": "My Tenant",
  • "subdomain": "my-tenant.vii.au01.mattr.global",
  • "environment": {
    },
  • "permissions": [
    ],
  • "client": {
    }
}
Retrieve tenant
Retrieves a tenant by its ID.


Analytic events


    

  • TENANT_RETRIEVE_START
    • 

  • TENANT_RETRIEVE_SUCCESS
    • 

  • TENANT_RETRIEVE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
tenantId
required
string <uuid> 
Unique ID of the tenant to retrieve.


 
Responses 
200
Tenant retrieved


400
Bad Request. The request was malformed or missing required parameters.


401
Unauthorized. The client is not recognized by authorization server.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


404
Not Found. The specified resource was not found.


500
Internal Server Error. An unexpected error occurred.


get/v1/tenants/{tenantId}
Request samples 
Response samples 
application/json
{
  • "id": "86cb97a9-5e80-4ed7-af13-a170752bb1ea",
  • "name": "My Tenant",
  • "subdomain": "my-tenant.vii.au01.mattr.global",
  • "environment": {
    },
  • "permissions": [
    ]
}
Delete tenant
Deletes a tenant by its ID.


Analytic events


    

  • TENANT_DELETE_START
    • 

  • TENANT_DELETE_SUCCESS
    • 

  • TENANT_DELETE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
tenantId
required
string <uuid> 
Unique ID of the tenant to delete.


 
Responses 
204
Tenant deleted


400
Bad Request. The request was malformed or missing required parameters.


401
Unauthorized. The client is not recognized by authorization server.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


404
Not Found. The specified resource was not found.


500
Internal Server Error. An unexpected error occurred.


delete/v1/tenants/{tenantId}
Request samples 
Response samples 
application/json
{
  • "code": "string",
  • "type": "string",
  • "message": "string",
  • "details": [
    ]
}
Clients
Retrieve clients
Retrieves a list of clients authorized to interact with the requested tenant.


Analytic events


    

  • TENANT_CLIENT_RETRIEVE_LIST_START
    • 

  • TENANT_CLIENT_RETRIEVE_LIST_SUCCESS
    • 

  • TENANT_CLIENT_RETRIEVE_LIST_FAIL
    • 



SecuritybearerAuth 
Request 
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 returned list.


 
 Example:  limit=2
cursor
string
Starting point for the list of entries.


 
 Example:  cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
Responses 
200
Clients retrieved


400
Bad Request. The request was malformed or missing required parameters.


401
Unauthorized. The client is not recognized by authorization server.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


404
Not Found. The specified resource was not found.


500
Internal Server Error. An unexpected error occurred.


get/v1/tenants/{tenantId}/clients
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}
Create a client
Creates a new client for the requested tenant.


Analytic events


    

  • TENANT_CLIENT_CREATE_START
    • 

  • TENANT_CLIENT_CREATE_SUCCESS
    • 

  • TENANT_CLIENT_CREATE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
tenantId
required
string <uuid> 
Unique ID of the tenant to create a client for.


 
Request Body schema: application/json
required
name
required
string
Name of the client associated with this tenant.


 
roles
required
Array of strings
A list of roles assigned to the client.


Items Enum: "admin" "issuer" "verifier" "dts-provider" "dts-consumer" "auditor"  
Responses 
201
Client created


400
Bad Request. The request was malformed or missing required parameters.


404
Not Found. The specified resource was not found.


500
Internal Server Error. An unexpected error occurred.


503
Service Unavailable. The server is temporarily unavailable to handle requests.


post/v1/tenants/{tenantId}/clients
Request samples 
application/json
{
  • "name": "Example client",
  • "roles": [
    ]
}
Response samples 
application/json
{
  • "clientId": "suC7IhmDIawnlqBlEOuIqBWoqppcdI5",
  • "clientSecret": "Qn_43J-SPeAPExeewH6YLn1rjVOCPsR_6_4lSmeUF-GSNuVAwdrBiGqerKUl8YZg",
  • "name": "Example client",
  • "permissions": [
    ],
  • "roles": [
    ]
}
Delete a client
Deletes an existing client of the specified tenant.


Analytic events


    

  • TENANT_CLIENT_DELETE_START
    • 

  • TENANT_CLIENT_DELETE_SUCCESS
    • 

  • TENANT_CLIENT_DELETE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
tenantId
required
string <uuid> 
Identifier of the tenant to delete the client from.


 
clientId
required
string  = 32 characters 
Identifier of the client to delete.


 
 Example:  suC7IhmDIawnlqBlEOuIqBWoqppcdI5
Responses 
204
Client deleted


400
Bad Request. The request was malformed or missing required parameters.


404
Not Found. The specified resource was not found.


500
Internal Server Error. An unexpected error occurred.


503
Service Unavailable. The server is temporarily unavailable to handle requests.


delete/v1/tenants/{tenantId}/clients/{clientId}
Request samples 
Response samples 
application/json
{
  • "code": "string",
  • "type": "string",
  • "message": "string",
  • "details": [
    ]
}
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 
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 
200
Successful response


401
Unauthorized


post/oauth/token
Request samples 
application/json
{
  • "client_id": "htf792W4p4MedZbnoWAs51EfqUt4d2",
  • "client_secret": "d3fYDX7FjPg1D1h2viARXsolPByQ9vMfg8LHylBy8F4s5KJLB4HhHGOxxqJnSj3G",
  • "audience": "https://my-tenant.vii.mattr.global",
  • "grant_type": "client_credentials"
}
Response samples 
application/json
{
  • "access_token": "s2dgbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6s2dcaEROemRDf5gbRVEwTTVSVFE0TmtZME9UZzVNVEpDTlVJNFJqRTBPREExTmpZMk1qazFPQSJ9",
  • "expires_in": 86400,
  • "token_type": "Bearer"
}
Users
Retrieve user information
Retrieves information about the currently authenticated user.


Analytic events


    

  • USER_USERINFO_RETRIEVE_START
    • 

  • USER_USERINFO_RETRIEVE_SUCCESS
    • 

  • USER_USERINFO_RETRIEVE_FAIL
    • 



SecuritybearerAuth 
Responses 
200
User information retrieved.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


500
Internal Server Error. An unexpected error occurred.


get/v1/userinfo
Request samples 
Response samples 
application/json
{
  • "id": "8f6d40a9-d913-45e8-aa3e-8c99d62cd8fb",
  • "email": "john-doe@example.com",
  • "name": "John Doe",
  • "status": "Active"
}
Update user information
Updates the information of the currently authenticated user.


Analytic events


    

  • USER_USERINFO_UPDATE_START
    • 

  • USER_USERINFO_UPDATE_SUCCESS
    • 

  • USER_USERINFO_UPDATE_FAIL
    • 



SecuritybearerAuth 
Request 
Request Body schema: application/json
required
name
required
string
User's full name.


 
Responses 
200
User information updated.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


500
Internal Server Error. An unexpected error occurred.


put/v1/userinfo
Request samples 
application/json
{
  • "name": "John Doe"
}
Response samples 
application/json
{
  • "id": "8f6d40a9-d913-45e8-aa3e-8c99d62cd8fb",
  • "email": "john-doe@example.com",
  • "name": "John Doe",
  • "status": "Active"
}
Members
Invite a tenant member
Invites a user to join the tenant and assigns roles to them within the tenant's context. 
If the user has not registered to the Self Service Portal yet, then they will receive an email with a link to accept the invite.
If the user has already registered, then they will be added as a member to the tenant immediately.


Analytic events


    

  • TENANT_MEMBER_INVITATION_CREATE_START
    • 

  • TENANT_MEMBER_INVITATION_CREATE_SUCCESS
    • 

  • TENANT_MEMBER_INVITATION_CREATE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
tenantId
required
string <uuid> 
Identifier of the tenant to add the member to.


 
 Example:  543e0579-87b9-4705-be78-8f7f54709838
Request Body schema: application/json
required
email
required
string <email> 
 
roles
required
Array of strings  non-empty 
The roles assigned to the user in the context of this tenant.


 
Responses 
200
Member invited


400
Bad Request. The request was malformed or missing required parameters.


401
Unauthorized. The client is not recognized by authorization server.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


404
Not Found. The specified resource was not found.


500
Internal Server Error. An unexpected error occurred.


post/v1/tenants/{tenantId}/invitations
Request samples 
application/json
{
  • "email": "john-doe@example.com",
  • "roles": [
    ]
}
Response samples 
application/json
{
  • "userId": "8f6d40a9-d913-45e8-aa3e-8c99d62cd8fb",
  • "status": "Pending",
  • "inviteExpiresAt": "2025-08-22T07:46:09.510Z"
}
Retrieve tenant members
Retrieves a list of all users that have access to the tenant.


Analytic events


    

  • TENANT_MEMBER_RETRIEVE_LIST_START
    • 

  • TENANT_MEMBER_RETRIEVE_LIST_SUCCESS
    • 

  • TENANT_MEMBER_RETRIEVE_LIST_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
tenantId
required
string <uuid> 
Identifier of the tenant to retrieve.


 
 Example:  543e0579-87b9-4705-be78-8f7f54709838
query Parameters
limit
number  [ 1 .. 1000 ] 
 Default:  100
Range size of returned list.


 
 Example:  limit=2
cursor
string
Starting point for the list of entries.


 
 Example:  cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
Responses 
200
Tenant's members retrieved


400
Bad Request. The request was malformed or missing required parameters.


401
Unauthorized. The client is not recognized by authorization server.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


500
Internal Server Error. An unexpected error occurred.


get/v1/tenants/{tenantId}/members
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}
Retrieve a tenant member
Retrieves an existing user that has access to the tenant.


Analytic events


    

  • TENANT_MEMBER_RETRIEVE_START
    • 

  • TENANT_MEMBER_RETRIEVE_SUCCESS
    • 

  • TENANT_MEMBER_RETRIEVE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
tenantId
required
string <uuid> 
Identifier of the tenant.


 
 Example:  543e0579-87b9-4705-be78-8f7f54709838
userId
required
string <uuid> 
Identifier of the user.


 
 Example:  818f7564-49cb-4003-b041-37aec302e2c9
Responses 
200
Tenant member retrieved


400
Bad Request. The request was malformed or missing required parameters.


401
Unauthorized. The client is not recognized by authorization server.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


500
Internal Server Error. An unexpected error occurred.


get/v1/tenants/{tenantId}/members/{userId}
Request samples 
Response samples 
application/json
{
  • "id": "8f6d40a9-d913-45e8-aa3e-8c99d62cd8fb",
  • "email": "john-doe@example.com",
  • "name": "John Doe",
  • "status": "Active",
  • "roles": [
    ],
  • "inviteExpiresAt": "2025-08-22T12:00:00.000Z"
}
Update a tenant membership
Updates the membership of a user in the tenant. This includes the roles assigned to this user for this tenant.


Analytic events


    

  • TENANT_MEMBERSHIP_UPDATE_START
    • 

  • TENANT_MEMBERSHIP_UPDATE_SUCCESS
    • 

  • TENANT_MEMBERSHIP_UPDATE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
tenantId
required
string <uuid> 
Identifier of the tenant.


 
 Example:  543e0579-87b9-4705-be78-8f7f54709838
userId
required
string <uuid> 
Identifier of the user who's membership is being updated.


 
 Example:  818f7564-49cb-4003-b041-37aec302e2c9
Request Body schema: application/json
required
roles
required
Array of strings
The roles assigned to the user.


 
Responses 
200
Membership updated.


400
Bad Request. The request was malformed or missing required parameters.


401
Unauthorized. The client is not recognized by authorization server.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


500
Internal Server Error. An unexpected error occurred.


put/v1/tenants/{tenantId}/memberships/{userId}
Request samples 
application/json
{
  • "roles": [
    ]
}
Response samples 
application/json
{
  • "userId": "879a5524-d515-4aee-824a-c52fdcd4eea6",
  • "tenantId": "8f49b206-e0bb-474d-8a4d-62186a9de886",
  • "roles": [
    ]
}
Delete a tenant membership
Removes the membership of a user from the specified tenant. This will remove all user permissions for this tenant.


Analytic events


    

  • TENANT_MEMBERSHIP_DELETE_START
    • 

  • TENANT_MEMBERSHIP_DELETE_SUCCESS
    • 

  • TENANT_MEMBERSHIP_DELETE_FAIL
    • 



SecuritybearerAuth 
Request 
path Parameters
tenantId
required
string <uuid> 
Identifier of the tenant the user is being removed from.


 
 Example:  543e0579-87b9-4705-be78-8f7f54709838
userId
required
string <uuid> 
Identifier of the user being removed.


 
 Example:  818f7564-49cb-4003-b041-37aec302e2c9
Responses 
204
User removed from tenant


400
Bad Request. The request was malformed or missing required parameters.


401
Unauthorized. The client is not recognized by authorization server.


403
Forbidden. The client is recognized by authorization server but is not allowed to access this resource.


500
Internal Server Error. An unexpected error occurred.


delete/v1/tenants/{tenantId}/memberships/{userId}
Request samples 
Response samples 
application/json
{
  • "code": "string",
  • "type": "string",
  • "message": "string",
  • "details": [
    ]
}