How to make a request to your MATTR VII tenant

MATTR VII capabilities are available through a suite of APIs, which means that to interact with your MATTR VII tenant, your implementation needs to make API requests to different endpoints.

This guide provides an overview of the steps required to make an API request to your MATTR VII tenant:

Choose an endpoint.
Obtain an access token (for protected endpoints).
Construct the request.
Handle the response.

We recommend using the MATTR VII Postman collection (opens in a new tab) to make requests to your MATTR VII tenant. While this isn't an explicit prerequisite it can really speed things up.

Prerequisites

Access to a MATTR VII tenant (Complete the sign up form for a free trial).
Login credentials provided as part of your onboarding process.

If you have not received your login credentials or have any questions, please contact us before proceeding.

Choose an endpoint

Select a MATTR VII endpoint to make a request to:

The API Reference offers an exhaustive list of all available endpoints and their request structures in different languages.
The Tutorials and Guides sections can be used to learn what endpoints are required for specific capabilities and workflows.

Obtain an access token

Request

Most of the MATTR VII endpoints are protected and require providing a bearer access token when making a request. If you are making a request to an unprotected endpoint, you do not need to obtain an access token and can continue to the next step.

Refer to the API Reference to determine which endpoints are protected and which are public.

Use your login credentials and make a request of the following structure to obtain an access token:

HTTP

POST https://{auth_server}/oauth/token

auth_server : Replace with the auth_url value from your login credentials.

Request body

JSON

{
    "client_id": "F5qaeLDdbvnU9zhA0j4eHUGCHwC1bKtt",
    "client_secret": "Wzc8J**********************************************************",
    "audience": "learn.vii.au01.mattr.global",
    "grant_type": "client_credentials"
}

client_id : Replace with the client_id value from your login credentials.
client_secret : Replace with the client_secret value from your login credentials.
audience : Replace with the audience value from your login credentials.
grant_type : Always use client_credentials as a static value, regardless of your specific login credentials.

Response

JSON

{
    "access_token": "eyJhb********************************************************************",
    "expires_in": 14400,
    "token_type": "Bearer"
}

The returned access_token value is a temporary token that must be used as a bearer token for all subsequent requests to protected endpoints on your tenant.

💡

You will need to obtain a new access token whenever it expires. Our Postman collection (opens in a new tab) includes a pre-request script that obtains an access token when it is missing or has expired.

Construct the request

Use the selected endpoint path and the auth_url value from your login credentials to construct the request:

{method} https://{tenant_url}/{path}

For example, a request to retrieve all Document Signer Certificates (DSCs) from a tenant whose tenant_url is learn.vii.au01.mattr.global should be constructed as follows:

GET https://learn.vii.au01.global/v2/credentials/mobile/document-signers

If the operation has a request body you should structure it too, based on the details provided in the API Reference, Tutorials or Guides.

Whatever tool or language your are using to make the request, make sure you include the access_token in the request header when making requests to protected endpoints. Refer to the API Reference for request samples.

Handle the response

The endpoint would respond with a standard HTTP status code (opens in a new tab) and a response body. These differ between endpoints and are detailed in the API Reference.

You can now adjust your implementation to handle these responses to achieve the desired outcome.