MATTR Learn

The MATTR VII API defines a set of capabilities that can be used to manage and interact with a MATTR VII tenant.

The MATTR VII API defines a set of capabilities that can be used to manage and interact with a MATTR VII tenant. This includes managing a Verifiable Credential across its lifecycle (issue-hold-verify) as well as various tenant administration and management tasks such as setting up a custom domain, creating identifiers and configuring issuance and verification workflows.

Getting Started

Choose an endpoint

Select a MATTR VII endpoint to make a request to. The following resources might be helpful:

The API Reference offers an exhaustive list of all available endpoints and their request structures in different languages.
Different tutorials and guides can be used to learn what endpoints are required for specific capabilities and workflows.
Refer to the Access control section to learn more about what endpoints your client will be able to access.

We recommend using the MATTR VII Postman collection to make requests to your MATTR VII tenant. While this isn't an explicit requirement it can really speed things up.

Obtain an access token

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 (as detailed in the API Reference), you do not need to obtain an access token and can continue to the next step.

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

Request

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

auth_server : Replace with the auth_url value obtained when you created your tenant.

Request Body

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

client_id : Replace with the client_id value obtained when you created your tenant.
client_secret : Replace with the client_secret value obtained when you created your tenant.
audience : Replace with the audience value obtained when you created your tenant.
grant_type : Always use client_credentials as a static value, regardless of your specific login credentials.

Response

Response body

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

The returned access_token will enable access to endpoints as per the role assigned to the client. Refer to Access control for more Information.
You will need to obtain a new access token whenever it expires. Our Postman collection includes a pre-request script that obtains an access token when it is missing or has expired.

Construct the request

Construct an API request using the selected endpoint path and the tenant_url value obtained when you created your tenant:

Request template

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

For example, a request to retrieve all IACAs from a tenant whose tenant_url is learn.vii.au01.mattr.global should be constructed as follows:

Request example

GET https://learn.vii.au01.mattr.global/v2/credentials/mobile/iacas

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

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 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.

Concepts

Pagination

Most list operations in the API enable cursor pagination using the cursor and limit query parameters:

Example on Retrieve List of Credentials

GET https://{tenant-url}/v2/credentials
?limit=100
&cursor=Y3JlYXRlZEF0PTIwMjAtMTAtMDhUMjMlM0ExMyUzQTE3Ljg5NtZGUxZWEyNzQ4MWI4

limit: determines how many entries are returned in that request, with a maximum value of 1000.
cursor: sets the location in the retrieved list to get the next batch of entries from. This is based on the returned nextCursor, found at the beginning of each returned range and identifies the last object in the list.

Requesting an entry after the last list value will return an empty data object:

{
"data": []
}

Not providing a query parameter defaults the response to return the first range of entries with a limit of 100.

Authorization

Access to the API is granted by our authorization provider. Use the auth_url, audience, client_id and client_secret provided with your tenant details to make a request to receive a bearer token from the auth provider. This token must then be used as an authorization header for all requests to protected endpoints (this is required for the majority of operations).

The returned bearer token will only enable access to endpoints as per your client's defined role. Refer to Access Control for more information.

Access control

MATTR VII uses Role-Based Access Control (RBAC) to manage permissions and access within a tenant. Each role grants access to specific capabilities, ensuring that users or clients only have access to the functionalities they need. Below is a list of available roles and their descriptions:

Tenant admin: Has full access to all tenant capabilities. This role is assigned to the default client when a new tenant is created.
Issuer: Has access to capabilities required for issuing and managing credentials of different formats across different channels.
Verifier: Has access to capabilities required for verifying credentials of different formats across different channels.
DTS provider: Has access to capabilities required for managing a Digital trust service (DTS).
DTS consumer: Has access to capabilities required to consume DTS information from a tenant.
Auditor: Has read-only access to analytics data.

Each restricted endpoint includes a Roles property that indicates what roles are required to access it.

Overview