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.

As a MATTR VII user, you are provided with the following details, required for accessing and engaging with your MATTR VII tenant:

{
  "audience": "YOUR_AUDIENCE_URL",
  "auth_url": "YOUR_AUTH_URL",
  "tenant_url": "YOUR_TENANT_URL",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

1. Use the auth_url, audience, client_id and client_secret to obtain an access token.
2. To make a request to your tenant, suffix the tenant_url with the endpoint route and include the obtained access token as a header bearer token. For example:

GET https://{tenant_url}/v1/dids

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.

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.

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.