MATTR VII API (v2.3.1)

Download OpenAPI specification:Download

Introduction

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 DIDs and configuring issuance and verification workflows. Refer to our API Changelog to see changes from previous versions.

Getting Started with our APIs

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",
"url": "YOUR_AUTH_URL",
"tenant_subdomain": "YOUR_TENANT_SUBDOMAIN",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}

If you have not received your tenant details or have questions, please contact us before proceeding.

Use the tenant_subdomain value provided with your tenant details to construct a URL of the following structure:

https://{YOUR_TENANT_SUBDOMAIN}.vii.au01.mattr.global

This is the base URL you should use for all requests to your tenant, suffixed by the endpoint route detailed for the specific API you are calling.

MATTR trial tenants are hosted on servers in Australia by default. If you are a customer and requested your tenant to be hosted in a different region, the au01 element in your URL should be replaced with a different value to correspond with your requested region. Please contact us if you are unsure what region to use.

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}/core/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 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).

bearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

bearerAuthOpenIdCredentials

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Analytics

Retrieve events

Returns a list of matching events from the tenant's event database.

The categories and types parameters filter based on an OR logic, whilst all other parameters use an "AND" logic. For example (categories OR types) AND requestIds AND dateFrom.

Authorizations:
query Parameters
ids
Array of Array of strings

Query by event IDs. These can be retrieved from event details.

Example: ids=e4c387e7-3e63-40f4-9a38-062aaae9ee50
requestIds
Array of Array of strings

Query by request IDs. These can be retrieved from event details. The response will include all the individual events that are part of the queried request.

Example: requestIds=e4c387e7-3e63-40f4-9a38-062aaae9ee50
categories
Array of Array of strings

Query by event categories. Uses an OR operation with types. Every category includes several event types. Each API endpoint details the event types it generates under the Analytic events heading.

Example: categories=dcc
types
Array of Array of strings

Query by event types. Uses an OR operation with categories. Every category includes several event types. Each API endpoint details the events it generates under the Analytic events heading.

Example: types=DCC_SIGN_START
dateFrom
string <date-time>

Query by event start date and time (inclusive), in ISO-8601 format.

Example:
dateTo
string <date-time>

Query by event end date and time (inclusive), in ISO-8601 format.

Example:
limit
number [ 1 .. 1000 ]
Default: 100

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/analytics/events?ids=e4c387e7-3e63-40f4-9a38-062aaae9ee50&requestIds=e4c387e7-3e63-40f4-9a38-062aaae9ee50&categories=dcc&types=DCC_SIGN_START&limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Messaging

Sign a message

Accepts a message payload and signs it with a JWS (JSON Web Signature) using the a specific key from the DID (Decentralized Identifier) provided in the request.

Analytic events

  • MESSAGING_SIGN_START
  • MESSAGING_SIGN_SUCCESS
  • MESSAGING_SIGN_FAIL
Authorizations:
Request Body schema: application/json

Sign message request

didUrl
required
string

The did key that will be used to sign the message, which must supports signing. You can obtain it from the DID document DID.localMetadata.initialDidDocument.authentication[0] path.

payload
required
object (JSONObjectMessage)

A JSON Object plaintext message

Responses

Request samples

Content type
application/json
{
  • "didUrl": "did:web:organization.com#2vcj3MjR4d",
  • "payload": {
    }
}

Response samples

Content type
application/json
"eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDprZXk6ejZNa21mazNtMldIQlVxVm94SlZ3R1NQejVrYmFKNnpBMXRwN1JRWUJiUUdtczNoI3o2TWttZmszbTJXSEJVcVZveEpWd0dTUHo1a2JhSjZ6QTF0cDdSUVlCYlFHbXMzaCJ9.eyJtc2ciOiJUaGlzIGlzIGEgcGF5bG9hZCJ9.5E9qEmmSOMHLABAr4A9VzuNKFaO4EDo2GSCMoxQm9zsE7eCmEEuaAxtNhOUdd-Wvj64vqBBVl84XB1Yg7X9wBg"

Verify a message

Verifies the siganture of a provided JWS (JSON Web Signature), validating that the payload has not been tampered with and verifying that the kid in the JWS header is the same as the iss value in the Request Object.

One use case for verifying a JWS with a DID is when the Mobile Wallet App sends a Request Object to an OpenID Provider as part of the Authorization Code Flow (as per https://openid.net/specs/openid-connect-core-1_0-final.html#RequestObject). The Request Object is wrapped in a JWS with a signature that is generated from the Subject DID on the mobile app. Therefore verifying the JWS proves that the mobile app has access to the private key of the Subject DID.

Analytic events

  • MESSAGING_VERIFY_START
  • MESSAGING_VERIFY_SUCCESS
  • MESSAGING_VERIFY_FAIL
Authorizations:
Request Body schema: application/json

Provide the JWS to verify

jws
string

JWS (JSON Web Siganture) in its compact form.

Responses

Request samples

Content type
application/json
{
  • "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Response samples

Content type
application/json
Example
{
  • "payload": "payload",
  • "didUrl": "did:web:organization.com#2vcj3MjR4d",
  • "did": "did:web:organization.com",
  • "verified": true,
  • "signerPublicJwk": {
    }
}

Encrypt a message

Encrypts the provided payload using into a JWM (JSON Web Message) format.

Analytic events

  • MESSAGING_ENCRYPT_START
  • MESSAGING_ENCRYPT_SUCCESS
  • MESSAGING_ENCRYPT_FAIL
Authorizations:
Request Body schema: application/json

Encryption parameters

senderDidUrl
required
string

The sender's DID URL, obtained from the id field of the first keyAgreement entry of its DID document (DID.localMetadata.initialDidDocument.keyAgreement[0].id). This must reference a key that supports key agreement.

recipientDidUrls
required
Array of strings

The intended recepient's Subject DID.

payload
required
object

The message to be encrypted.

Responses

Request samples

Content type
application/json
Example
{
  • "senderDidUrl": "did:web:learn.vii.au01.mattr.global#z6LShWb1DVC2gkxoQ91VwHmNhci2A4NdVH4srFvLiTP6ETBK",
  • "recipientDidUrls": [
    ],
  • "payload": {}
}

Response samples

Content type
application/json
{
  • "jwe": {
    }
}

Decrypt a message

Decrypts a provided message where the tenant manages the keys for the defined recipientDidUrl.

Analytic events

  • MESSAGING_DECRYPT_START
  • MESSAGING_DECRYPT_SUCCESS
  • MESSAGING_DECRYPT_FAIL
Authorizations:
Request Body schema: application/json

Decryption parameters

required
string or EncryptedMessage (object)

The jwe object to be decrypted. It can be extracted from the jwe attribute of the response body you get when encrypting a message. Alternatively, you can use a jwe string using Base64 encoding method and following the JWE open-standard: BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || ASE64URL(JWE Authentication Tag)

Responses

Request samples

Content type
application/json
{
  • "jwe": "eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDp3ZWI6bWF0dHIuZ2xvYmFsI0V5MkN2V2N5MzQifQ.eyJtZXNzYWdlIjoidGVzdCJ9.dMvOGkfbRrjUJL7XYYAp1UxoHlt8J0N5_vRRLpTEHtQ4s8lwnMd0lhg7HiZVfvEyzk54f6J0CgTV5oHzVscdAA"
}

Response samples

Content type
application/json
{
  • "payload": "string",
  • "senderDidUrl": "did:web:organization.com#2vcj3MjR4d",
  • "senderPublicJwk": { },
  • "recipientDidUrl": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
}

Send a message

Sends an encrypted JWM (JSON Web Messaging) format message to a service endpoint defined in a public DID document.

Analytic events

  • MESSAGING_SEND_START
  • MESSAGING_SEND_SUCCESS
  • MESSAGING_SEND_FAIL
Authorizations:
Request Body schema: application/json
to
string

Recipient DID.

string or object

Message in JWE (JSON Web Encryption) format. This endpoint only accepts Encrypted payloads to ensure that messages are encrypted-at-rest whilst in messaging inboxes. The message should be encrypted for the recipient based on a key available in the DID Document.

Responses

Request samples

Content type
application/json
{
  • "to": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d",
  • "message": {
    }
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Inboxes

Create an inbox

Creates an inbox that can register DIDs and then hold messages sent to those DIDs service points.

Analytic events

  • MESSAGING_INBOX_CREATE_START
  • MESSAGING_INBOX_CREATE_SUCCESS
  • MESSAGING_INBOX_CREATE_FAIL
Authorizations:
Request Body schema: application/json

Inbox configuration

name
required
string non-empty

Inbox name.

Responses

Request samples

Content type
application/json
{
  • "name": "My_Inbox"
}

Response samples

Content type
application/json
{
  • "id": "f04faabf-cea8-4f39-95b3-0ce357ac4d03",
  • "name": "My_Inbox"
}

List inboxes

Returns a list of all inboxes on the tenant.

Analytic events

  • MESSAGING_INBOX_RETRIEVE_LIST_START
  • MESSAGING_INBOX_RETRIEVE_LIST_SUCCESS
  • MESSAGING_INBOX_RETRIEVE_LIST_FAIL
Authorizations:
query Parameters
limit
number [ 1 .. 1000 ]
Default: 100

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/messaging/inboxes?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Retrieve an inbox

Retrieves an inbox based on its ID.

Analytic events

  • MESSAGING_INBOX_RETRIEVE_START
  • MESSAGING_INBOX_RETRIEVE_SUCCESS
  • MESSAGING_INBOX_RETRIEVE_FAIL
Authorizations:
path Parameters
id
required
string

Inbox ID

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/messaging/inboxes/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "f04faabf-cea8-4f39-95b3-0ce357ac4d03",
  • "name": "My_Inbox"
}

Update an inbox

Update the inbox configurations

Authorizations:
path Parameters
id
required
string

Inbox ID

Request Body schema: application/json

Updates an inbox name.

Analytic events

  • MESSAGING_INBOX_UPDATE_START
  • MESSAGING_INBOX_UPDATE_SUCCESS
  • MESSAGING_INBOX_UPDATE_FAIL
name
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "f04faabf-cea8-4f39-95b3-0ce357ac4d03",
  • "name": "My_Inbox"
}

Delete an inbox

Deletes an inbox by providing its ID.

Analytic events

  • MESSAGING_INBOX_DELETE_START
  • MESSAGING_INBOX_DELETE_SUCCESS
  • MESSAGING_INBOX_DELETE_FAIL
Authorizations:
path Parameters
id
required
string

Inbox ID

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/messaging/inboxes/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Register DID with an inbox

Register the provided DID to the requested inbox.

DID registration with inboxes is currently limited to did:key'

Analytic events

  • MESSAGING_INBOX_DID_REGISTER_START
  • MESSAGING_INBOX_DID_REGISTER_SUCCESS
  • MESSAGING_INBOX_DID_REGISTER_FAIL
Authorizations:
path Parameters
id
required
string

Requested inbox ID

Request Body schema: application/json

DID registration information

did
required
string

URI of the DID to register with this inbox.

jwt
string

Responses

Request samples

Content type
application/json
{
  • "did": "string",
  • "jwt": "string"
}

Response samples

Content type
application/json
{
  • "did": "string"
}

Retrieve inbox DIDs

Retrieves a list of all the DIDs registered with the requested inbox.

Analytic events

  • MESSAGING_INBOX_DID_RETRIEVE_LIST_START
  • MESSAGING_INBOX_DID_RETRIEVE_LIST_SUCCESS
  • MESSAGING_INBOX_DID_RETRIEVE_LIST_FAIL
Authorizations:
path Parameters
id
required
string

Requested inbox ID

query Parameters
limit
number [ 1 .. 1000 ]
Default: 100

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/messaging/inboxes/:id/dids?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": [
    ]
}

Unregister DID with an inbox

Unregisters a DID from the requested inbox.

Analytic events

  • MESSAGING_INBOX_DID_UNREGISTER_START
  • MESSAGING_INBOX_DID_UNREGISTER_SUCCESS
  • MESSAGING_INBOX_DID_UNREGISTER_FAIL
Authorizations:
path Parameters
id
required
string

Requested inbox ID

did
required
string

DID

Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/messaging/inboxes/:id/dids/:did' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Retrieve all messages

Retrieving all the messages from an inbox

Analytic events

  • MESSAGING_INBOX_MESSAGE_RETRIEVE_LIST_START
  • MESSAGING_INBOX_MESSAGE_RETRIEVE_LIST_SUCCESS
  • MESSAGING_INBOX_MESSAGE_RETRIEVE_LIST_FAIL
Authorizations:
path Parameters
id
required
string

Requested inbox ID

query Parameters
limit
number [ 1 .. 1000 ]
Default: 100

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/messaging/inboxes/:id/messages?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": [
    ]
}

Retrieve a message

Retrieves a message from the requested inbox by providing its ID.

Analytic events

  • MESSAGING_INBOX_MESSAGE_RETRIEVE_START
  • MESSAGING_INBOX_MESSAGE_RETRIEVE_SUCCESS
  • MESSAGING_INBOX_MESSAGE_RETRIEVE_FAIL
Authorizations:
path Parameters
id
required
string

Requested inbox ID

messageid
required
string

Requested message ID

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/messaging/inboxes/:id/messages/:messageid' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "name": "string",
  • "createdAt": "2019-08-24",
  • "id": "string",
  • "inboxId": "string",
  • "payload": "string"
}

Delete a message

Deletes a message from the requested inbox by providing its ID.

Analytic events

  • MESSAGING_INBOX_MESSAGE_DELETE_START
  • MESSAGING_INBOX_MESSAGE_DELETE_SUCCESS
  • MESSAGING_INBOX_MESSAGE_DELETE_FAIL
Authorizations:
path Parameters
id
required
string

Requested inbox ID

messageid
required
string

Requested message ID

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/messaging/inboxes/:id/messages/:messageid' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
Example
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Security

Create API Auth Token

Returns an API access token. This token must then be used as an authorization header for all requests to protected endpoints (this is required for the majority of operations).

This request must be made to an authentication server based on your tenant's region:

  • Sydney, Australia: auth.vii.au01.mattr.global
  • Montreal, Cadanda: auth.vii.ca01.mattr.global
  • Frankfurt, Germany, Europe: auth.vii.eu01.mattr.global
  • Oregon, United States: auth.vii.us01.mattr.global

Your region details as well as required client_id and client_secret are provided as part of onboarding, or retrieved when you create a tenant on the Self Service Portal. If you do not have your tenant details, or have any other questions, please contact us before proceeding.

Request Body schema: application/json
client_id
required
string

Use the client_id value provided with your tenant details, or retrieved when you created a tenant on the Self Service Portal.

client_secret
required
string

Use the client_secret value provided with your tenant details, or retrieved when you created a tenant on the Self Service Portal.

audience
required
string

Use your tenant URL.

grant_type
required
string

Use client_credentials.

Responses

Request samples

Content type
application/json
{
  • "client_id": "htf792W4p4MedZbnoWAs51EfqUt4d2",
  • "client_secret": "d3fYDX7FjPg1D1h2viARXsolPByQ9vMfg8LHylBy8F4s5KJLB4HhHGOxxqJnSj3G",
  • "grant_type": "client_credentials"
}

Response samples

Content type
application/json
{
  • "access_token": "s2dgbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6s2dcaEROemRDf5gbRVEwTTVSVFE0TmtZME9UZzVNVEpDTlVJNFJqRTBPREExTmpZMk1qazFPQSJ9",
  • "expires_in": 86400,
  • "token_type": "Bearer"
}

Custom Domain

Configure custom domain

Creates a custom domain configuration on your tenant. You can configure a custom domain for a specific MATTR VII tenant to represent your brand and instil trust with your end-users. Any MATTR VII tenant can only have one custom domain. Refer to our tutorial for more information.

Custom domains are only available as part of our paid plans, and trial accounts do not include ongoing access to custom domains. The APIs are available for you to trial the feature, but they may be deactivated unless you switch to a paid plan.

Analytic events

  • CONFIG_CUSTOM_DOMAIN_CREATE_START
  • CONFIG_CUSTOM_DOMAIN_CREATE_SUCCESS
  • CONFIG_CUSTOM_DOMAIN_CREATE_FAIL
Authorizations:
Request Body schema:

The custom domain payload

name
required
string

Insert a name for the custom domain that will be displayed to digital wallet holders when they receive credential offers or verification requests from this tenant.

logoUrl
required
string

Insert a URL for a square logo that will be displayed to digital wallet holders when they receive credential offers or verification requests from your MATTR VII tenant:

  • URL must be publicly available.
  • Must be a square image, recommended 64x64 px in size
  • png and jpg files are supported.
  • The recommended maximum size is 15 KB.
domain
required
string

Insert the full custom domain, leaving out the protocol (e.g. https://).

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{
  • "name": "Example Corp",
  • "domain": "example.com",
  • "verificationToken": "8c6f36c1-91ff-439d-a518-48cf7ef421ef",
  • "isVerified": false
}

Retrieve custom domain

Returns your tenant's custom domain configuration and its verification status.

Analytic events

  • CONFIG_CUSTOM_DOMAIN_RETRIEVE_START
  • CONFIG_CUSTOM_DOMAIN_RETRIEVE_SUCCESS
  • CONFIG_CUSTOM_DOMAIN_RETRIEVE_FAIL
Authorizations:

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/config/domain' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "name": "Example Corp",
  • "domain": "example.com",
  • "verificationToken": "8c6f36c1-91ff-439d-a518-48cf7ef421ef",
  • "isVerified": true,
  • "verifiedAt": "2024-01-31T20:31:48.340Z"
}

Delete custom domain

Deletes the custom domain configuration on your tenant.

Deleting your custom domain configuration breaks the linkage with any credentials issued under the custom domain. These credentials will no longer be valid.

Analytic events

  • CONFIG_CUSTOM_DOMAIN_DELETE_START
  • CONFIG_CUSTOM_DOMAIN_DELETE_SUCCESS
  • CONFIG_CUSTOM_DOMAIN_DELETE_FAIL
Authorizations:

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/config/domain' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Update custom domain

Updates the custom domain configuration.

Analytic events

  • CONFIG_CUSTOM_DOMAIN_UPDATE_START
  • CONFIG_CUSTOM_DOMAIN_UPDATE_SUCCESS
  • CONFIG_CUSTOM_DOMAIN_UPDATE_FAIL
Authorizations:
Request Body schema: application/json
id
string
name
required
string

Insert a name for the custom domain that will be displayed to digital wallet holders when they receive credential offers or verification requests from this tenant.

logoUrl
required
string

Insert a URL for a square logo that will be displayed to digital wallet holders when they receive credential offers or verification requests from your MATTR VII tenant:

  • URL must be publicly available.
  • Must be a square image, recommended 64x64 px in size
  • png and jpg files are supported.
  • The recommended maximum size is 15 KB.
domain
required
string

Insert the full custom domain, leaving out the protocol (e.g. https://).

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "name": "Example Corp",
  • "domain": "example.com",
  • "verificationToken": "8c6f36c1-91ff-439d-a518-48cf7ef421ef",
  • "isVerified": true,
  • "verifiedAt": "2021-04-15T07:37:25.008Z"
}

Verify custom domain

Verifies that you have control of the configured custom domain by examining its TXT record.

Your custom domain will not be active until you verify it. Refer to Verify domain ownership for more information.

Analytic events

  • CONFIG_CUSTOM_DOMAIN_VERIFY_START
  • CONFIG_CUSTOM_DOMAIN_VERIFY_SUCCESS
  • CONFIG_CUSTOM_DOMAIN_VERIFY_FAIL
Authorizations:

Responses

Request samples

curl -i -X POST \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/config/domain/verify' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

DIDs

Create a DID

Takes a supported DID method and returns a new DID with its generated keys and required information. This endpoint also registers the DID Document when applicable.

MATTR VII currently supports creating DIDs of the following methods:

  • did:key: The most basic type of DID. The public key forms the DID and has no further data associated with it.
  • did:web: This type of DID requires hosting the DID document on a publicly accessible domain in order to make the document and its contents available.

Analytic events

  • DID_CREATE_START
  • DID_CREATE_SUCCESS
  • DID_CREATE_FAIL
Authorizations:
Request Body schema: application/json

Options for creating the decentralized identifier

method
required
string

Used to determine the type of DID to be created based on its DID method.

Enum: "key" "web"
object non-empty

To define a key type for a did:key or to define a domain for did:web

Responses

Request samples

Content type
application/json
Example
{
  • "method": "web",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "did": "did:web:learn.vii.au01.mattr.global",
  • "registrationStatus": "COMPLETED",
  • "localMetadata": {
    }
}

Retrieve a list of DIDs

Returns a list of all DIDs (Decentralized Identifiers) managed by the tenant and their associated meta-data.

Analytic events

  • DID_RETRIEVE_LIST_START
  • DID_RETRIEVE_LIST_SUCCESS
  • DID_RETRIEVE_LIST_FAIL
Authorizations:
query Parameters
limit
number [ 1 .. 1000 ]
Default: 100

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/dids?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Resolve a DID

Retrieves a DID and its metadata from the tenant by its URI. This may involve a network call depending on the method involved:

  • For did:key the public key is encapsulated in the DID URI itself.
  • For did:web it must be resolved by accessing the /.well-known/did.json path on its domain.

Analytic events

  • DID_RETRIEVE_START
  • DID_RETRIEVE_SUCCESS
  • DID_RETRIEVE_FAIL
Authorizations:
path Parameters
id
required
string <did>

DID

Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/dids/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "did": "did:web:learn.vii.au01.mattr.global",
  • "registrationStatus": "COMPLETED",
  • "localMetadata": {
    }
}

Delete a DID

Deletes a DID and all associated metadata by providing its URI. This includes all the removal of all associated private keys from the Key Management System (KMS).

For ledger-based DIDs the public DID Document will still be available. This means that for did:web you will need to manually remove the did.json from your hosted domain.

Analytic events

  • DID_DELETE_START
  • DID_DELETE_SUCCESS
  • DID_DELETE_FAIL
Authorizations:
path Parameters
id
required
string <did>

DID

Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/dids/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Well known DID configuration

Returns a list of Decentralized Identifier (DID) Configuration entries from the tenant. These are automatically created for all DIDS created on a tenant so that they can be used by any party aiming to establish and verify the domain-DID linkage by exposing cryptographic proofs. Thus, this endpoint is unprotected, public facing and can be deterministically found at the root of the tenant subdomain or alias by any party. Refer to Well Known DID Configuration on the Decentralized Identity Foundation website for more information.

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/.well-known/did-configuration'

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

IACA

Create an IACA

Creates a new IACA that can be used to sign new Document Signer Certificates (DSCs).

Analytic events

  • MOBILE_CREDENTIAL_IACA_CREATE_START
  • MOBILE_CREDENTIAL_IACA_CREATE_SUCCESS
  • MOBILE_CREDENTIAL_IACA_CREATE_FAIL
Authorizations:
Request Body schema: application/json
commonName
string
Default: "{tenantHost} IACA"

This optional parameter indicates the common name of the IACA certificate. When specified, the value must be a valid PrintableString. If not provided and a custom domain is configured and verified, the custom domain is used. If no custom domain is configured, the tenant subdomain is used.

country
string

This optional parameter indicates the issuer country. If not provided, a country is selected based on the region of the tenant subdomain cloud host. When specified, the value must be uppercase and a valid country code as per ISO 3166-1 alpha-2.

notAfter
string

This optional parameter indicates the date after which the IACA should no longer be used as a source of trust. When omitted, defaults to 10 years from date of issuance.

Responses

Request samples

Content type
application/json
{
  • "commonName": "https://{tenant-subdomain}.vii.mattr.global IACA",
  • "country": "NZ",
  • "notAfter": "2034-09-26"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "certificatePem": "-----BEGIN CERTIFICATE-----\r\nMIICDjCCAbSgAwIBAgIKdeZsA5NPKimuAzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\r\nEwJOWjATBgNVBAMTDEV4YW1wbGUgSUFDQTAeFw0yMzA5MTEyMzM0MjJaFw0zMzA5\r\nMDgyMzM0MjJaMCIxIDAJBgNVBAYTAk5aMBMGA1UEAxMMRXhhbXBsZSBJQUNBMFkw\r\nEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEBbK7JKKFMWuu8kHQK2qaML+MQ0Ykk3Qg\r\n/p3TC6lQKvYJozPSpLXbJQIzMPq9u/dG+j4vq1iX/G/jFIwfiEiKEqOB0TCBzjAS\r\nBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIABjAdBgNVHQ4EFgQU9zTh\r\nKsqFxAgRJDDGW1au+ewJK6owHgYDVR0SBBcwFYYTaHR0cHM6Ly9leGFtcGxlLmNv\r\nbTBpBgNVHR8EYjBgMF6gXKBahlhodHRwczovL2V4YW1wbGUuY29tL3YyL2NyZWRl\r\nbnRpYWxzL21vYmlsZS9pYWNhcy8yZTg5YzE1Ni0zMWQ1LTQ3ODMtYmQ1OS05MDU1\r\nYjVmOGU3ZDIvY3JsMAoGCCqGSM49BAMCA0gAMEUCIQDD+eU8iOsYYC0v41L94fhF\r\nZ0brPo4gx2aRxrhE3NLFpwIgIgHCPBXJ+JICJg3K7dEsr153So4SEZzAA1rRn4eF\r\nvkM=\r\n-----END CERTIFICATE-----\r\n",
  • "certificateData": {
    },
  • "publicKeyJwk": {
    }
}

Retrieve all IACAs

Retrieves all existing IACAs from the tenant.

Analytic events

  • MOBILE_CREDENTIAL_IACA_RETRIEVE_LIST_START
  • MOBILE_CREDENTIAL_IACA_RETRIEVE_LIST_SUCCESS
  • MOBILE_CREDENTIAL_IACA_RETRIEVE_LIST_FAIL
Authorizations:

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/mobile/iacas' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": "string"
}

Delete an IACA

Deletes an existing IACA by providing its ID.

Analytic events

  • MOBILE_CREDENTIAL_IACA_DELETE_START
  • MOBILE_CREDENTIAL_IACA_DELETE_LIST_SUCCESS
  • MOBILE_CREDENTIAL_IACA_DELETE_LIST_FAIL
Authorizations:
path Parameters
iacaId
required
string <uuid>

IACA ID

Example: 497f6eca-6276-4993-bfeb-53cbbbba6f08

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/mobile/iacas/:iacaId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

DSCs

Create a DSC

Creates a new Document Signer Certificate (DSC) that can be used to sign new Mobile Credentials.

Analytic events

  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_CREATE_START
  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_CREATE_SUCCESS
  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_CREATE_FAIL
Authorizations:
Request Body schema: application/json
active
required
boolean

This required parameter defines the status of the created DSC. Only active DSCs (true) can be used to sign Mobile Credentials.

commonName
string

This optional parameter indicates the common name of the DSC certificate. When specified, the value must be a valid PrintableString. If not provided and a custom domain is configured and verified, the custom domain is used. If no custom domain is configured, the tenant subdomain is used.

notAfter
string

Optional date after which the DSC can no longer be used to sign Mobile Credentials. If not provided, defaults to 365 days from issuance date. Maximum value can be 457 days from issuance date.

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "commonName": "https://{tenant-subdomain}.vii.mattr.global Document Signer",
  • "notAfter": "2034-09-26"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "active": true,
  • "publicKey": {
    },
  • "certificatePem": "-----BEGIN CERTIFICATE-----\\r\\nMIICbzCCAhSgAwIBAgIKfS7sskyJEh+DOzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\\r\\nEwJOWjATBgNVBAMTDEV4YW1wbGUgSUFDQTAeFw0yMzA5MTEyMzM0MjJaFw0yNDA5\\r\\nMTAyMzM0MjJaMDExLzAJBgNVBAYTAk5aMCIGA1UEAxMbZXhhbXBsZS5jb20gRG9j\\r\\ndW1lbnQgU2lnbmVyMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7fa+jv9zCtHQ\\r\\nmKn7o1dS6lBHD5thlhPqjlx7qEfqy8Im9AcQJDal2sr/fUxhHwf/G4ublS7AL04U\\r\\n73dzr/ozxaOCASEwggEdMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLdNNPTmPxt0\\r\\nLqvlZnV/QL86MXOxMB8GA1UdIwQYMBaAFPc04SrKhcQIESQwxltWrvnsCSuqMA4G\\r\\nA1UdDwEB/wQEAwIAgDAeBgNVHREEFzAVhhNodHRwczovL2V4YW1wbGUuY29tMB4G\\r\\nA1UdEgQXMBWGE2h0dHBzOi8vZXhhbXBsZS5jb20waQYDVR0fBGIwYDBeoFygWoZY\\r\\naHR0cHM6Ly9leGFtcGxlLmNvbS92Mi9jcmVkZW50aWFscy9tb2JpbGUvaWFjYXMv\\r\\nMmU4OWMxNTYtMzFkNS00NzgzLWJkNTktOTA1NWI1ZjhlN2QyL2NybDASBgNVHSUE\\r\\nCzAJBgcogYxdBQECMAoGCCqGSM49BAMCA0kAMEYCIQCfgn6+QoNfDVelJANl+Jp9\\r\\ncq7X9paZylfnI6UGr1FM6gIhAIzhiyclDa8+/ZSRfu7KfgGrNRaJ8YQ6vevskJls\\r\\nIavC\\r\\n-----END CERTIFICATE-----\\r\\n",
  • "certificateFingerprint": "f6cad6e579d70b3973efa60624af731a580d1a11a7579e70f2f10f059dc86172",
  • "certificateData": {
    }
}

Retrieve all DSCs

Retrieves all existing DSCs from the tenant.

Analytic events

  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_RETRIEVE_LIST_START
  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_RETRIEVE_LIST_SUCCESS
  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_RETRIEVE_LIST_FAIL
Authorizations:

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/mobile/documentsigners' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": "string"
}

Update a DSC

Updates an existing DSC by providing its ID and active parameter.

Analytic events

  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_UPDATE_START
  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_UPDATE_SUCCESS
  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_UPDATE_FAIL
Authorizations:
path Parameters
documentSignerId
required
string <uuid>

DSC ID

Example: d2c9f2aa-fc69-4fbc-9b85-0c00591d72f6
Request Body schema: application/json
active
required
boolean

This required parameter defines the status of the created DSC. Only active DSCs can be used to sign Mobile Credentials.

Responses

Request samples

Content type
application/json
{
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "active": true,
  • "publicKey": {
    },
  • "certificatePem": "-----BEGIN CERTIFICATE-----\\r\\nMIICbzCCAhSgAwIBAgIKfS7sskyJEh+DOzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\\r\\nEwJOWjATBgNVBAMTDEV4YW1wbGUgSUFDQTAeFw0yMzA5MTEyMzM0MjJaFw0yNDA5\\r\\nMTAyMzM0MjJaMDExLzAJBgNVBAYTAk5aMCIGA1UEAxMbZXhhbXBsZS5jb20gRG9j\\r\\ndW1lbnQgU2lnbmVyMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7fa+jv9zCtHQ\\r\\nmKn7o1dS6lBHD5thlhPqjlx7qEfqy8Im9AcQJDal2sr/fUxhHwf/G4ublS7AL04U\\r\\n73dzr/ozxaOCASEwggEdMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLdNNPTmPxt0\\r\\nLqvlZnV/QL86MXOxMB8GA1UdIwQYMBaAFPc04SrKhcQIESQwxltWrvnsCSuqMA4G\\r\\nA1UdDwEB/wQEAwIAgDAeBgNVHREEFzAVhhNodHRwczovL2V4YW1wbGUuY29tMB4G\\r\\nA1UdEgQXMBWGE2h0dHBzOi8vZXhhbXBsZS5jb20waQYDVR0fBGIwYDBeoFygWoZY\\r\\naHR0cHM6Ly9leGFtcGxlLmNvbS92Mi9jcmVkZW50aWFscy9tb2JpbGUvaWFjYXMv\\r\\nMmU4OWMxNTYtMzFkNS00NzgzLWJkNTktOTA1NWI1ZjhlN2QyL2NybDASBgNVHSUE\\r\\nCzAJBgcogYxdBQECMAoGCCqGSM49BAMCA0kAMEYCIQCfgn6+QoNfDVelJANl+Jp9\\r\\ncq7X9paZylfnI6UGr1FM6gIhAIzhiyclDa8+/ZSRfu7KfgGrNRaJ8YQ6vevskJls\\r\\nIavC\\r\\n-----END CERTIFICATE-----\\r\\n",
  • "certificateFingerprint": "f6cad6e579d70b3973efa60624af731a580d1a11a7579e70f2f10f059dc86172",
  • "certificateData": {
    }
}

Retrieve a DSC

Retrieves an existing DSC by providing its ID.

Analytic events

  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_RETRIEVE_START
  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_RETRIEVE_SUCCESS
  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_RETRIEVE_FAIL
Authorizations:
path Parameters
documentSignerId
required
string <uuid>

DSC ID

Example: d2c9f2aa-fc69-4fbc-9b85-0c00591d72f6

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/mobile/documentsigners/:documentSignerId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "active": true,
  • "publicKey": {
    },
  • "certificatePem": "-----BEGIN CERTIFICATE-----\\r\\nMIICbzCCAhSgAwIBAgIKfS7sskyJEh+DOzAKBggqhkjOPQQDAjAiMSAwCQYDVQQG\\r\\nEwJOWjATBgNVBAMTDEV4YW1wbGUgSUFDQTAeFw0yMzA5MTEyMzM0MjJaFw0yNDA5\\r\\nMTAyMzM0MjJaMDExLzAJBgNVBAYTAk5aMCIGA1UEAxMbZXhhbXBsZS5jb20gRG9j\\r\\ndW1lbnQgU2lnbmVyMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7fa+jv9zCtHQ\\r\\nmKn7o1dS6lBHD5thlhPqjlx7qEfqy8Im9AcQJDal2sr/fUxhHwf/G4ublS7AL04U\\r\\n73dzr/ozxaOCASEwggEdMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLdNNPTmPxt0\\r\\nLqvlZnV/QL86MXOxMB8GA1UdIwQYMBaAFPc04SrKhcQIESQwxltWrvnsCSuqMA4G\\r\\nA1UdDwEB/wQEAwIAgDAeBgNVHREEFzAVhhNodHRwczovL2V4YW1wbGUuY29tMB4G\\r\\nA1UdEgQXMBWGE2h0dHBzOi8vZXhhbXBsZS5jb20waQYDVR0fBGIwYDBeoFygWoZY\\r\\naHR0cHM6Ly9leGFtcGxlLmNvbS92Mi9jcmVkZW50aWFscy9tb2JpbGUvaWFjYXMv\\r\\nMmU4OWMxNTYtMzFkNS00NzgzLWJkNTktOTA1NWI1ZjhlN2QyL2NybDASBgNVHSUE\\r\\nCzAJBgcogYxdBQECMAoGCCqGSM49BAMCA0kAMEYCIQCfgn6+QoNfDVelJANl+Jp9\\r\\ncq7X9paZylfnI6UGr1FM6gIhAIzhiyclDa8+/ZSRfu7KfgGrNRaJ8YQ6vevskJls\\r\\nIavC\\r\\n-----END CERTIFICATE-----\\r\\n",
  • "certificateFingerprint": "f6cad6e579d70b3973efa60624af731a580d1a11a7579e70f2f10f059dc86172",
  • "certificateData": {
    }
}

Delete a DSC

Deletes an existing DSC by providing its ID.

Analytic events

  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_DELETE_START
  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_DELETE_SUCCESS
  • MOBILE_CREDENTIAL_DOCUMENT_SIGNER_DELETE_FAIL
Authorizations:
path Parameters
documentSignerId
required
string <uuid>

DSC ID

Example: d2c9f2aa-fc69-4fbc-9b85-0c00591d72f6

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/mobile/documentsigners/:documentSignerId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Webhooks

Create Webhook

Creates a new webhook for this tenant.

Analytic events

  • WEBHOOK_CREATE_START
  • WEBHOOK_CREATE_SUCCESS
  • WEBHOOK_CREATE_FAIL
Authorizations:
Request Body schema: application/json

The webhook payload

events
required
Array of strings

This array includes the event types that will trigger this Webhook. The following events are currently supported:

  • OpenIdCredentialIssued: Triggered upon completion of an OpenID4VCI issuance flow.
  • OidcIssuerCredentialIssued: Triggered upon completion of an OICD Bridge issuance flow.
Items Enum: "OidcIssuerCredentialIssued" "OpenIdCredentialIssued"
url
required
string <uri>

This is the URL that will receive the Webhook events data payload when they are triggered by MATTR VII for the specified events:

  • Must be a valid URL.
  • Must use the HTTPS protocol.
  • Must not be an IP address.
  • Must not include query parameters or has fragments.
  • Non-ASCII characters are normalised.
  • Must return a 2xx response, otherwise it will go through a retry cycle and eventually fail.
disabled
boolean

Indicates whether or not the Webhook is disabled. When set to true the webhook is disabled, and notifications for events associated with it will not be sent. If no value is provided, defaults to false.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
  • "events": [
    ],
  • "disabled": false
}

Retrieve all Webhooks

Retrieves a list of webhooks configured on the tenant.

Analytic events

  • WEBHOOK_RETRIEVE_LIST_START
  • WEBHOOK_RETRIEVE_LIST_SUCCESS
  • WEBHOOK_RETRIEVE_LIST_FAIL
Authorizations:
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned webhook entries, default 100

Example: limit=2
cursor
string

Starting point for the range of webhook entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/webhooks?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjItMDgtMjJUMDElM0E1OSUzQTE5LjYyMFomaWQ9MGMwOTk2MTEtMTljNC00ZjI5LTg3MjQtNmI5ZTViYTFlZjdj"
}

Retrieve Webhook

Retrieve a specific Webhook by providing its ID.

Analytic events

  • WEBHOOK_RETRIEVE_START
  • WEBHOOK_RETRIEVE_SUCCESS
  • WEBHOOK_RETRIEVE_FAIL
Authorizations:
path Parameters
id
required
string <uuid>

The requested Webhook ID.

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/webhooks/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
  • "events": [
    ],
  • "disabled": false
}

Update Webhook

Updates an existing Webhook by providing its ID.

Analytic events

  • WEBHOOK_UPDATE_START
  • WEBHOOK_UPDATE_SUCCESS
  • WEBHOOK_UPDATE_FAIL
Authorizations:
path Parameters
id
required
string <uuid>

Webhook ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
Request Body schema: application/json

Update Webhook

events
required
Array of strings

This array includes the event types that will trigger this Webhook. The following events are currently supported:

  • OpenIdCredentialIssued: Triggered upon completion of an OpenID4VCI issuance flow.
  • OidcIssuerCredentialIssued: Triggered upon completion of an OICD Bridge issuance flow.
Items Enum: "OidcIssuerCredentialIssued" "OpenIdCredentialIssued"
url
required
string <uri>

This is the URL that will receive the Webhook events data payload when they are triggered by MATTR VII for the specified events:

  • Must be a valid URL.
  • Must use the HTTPS protocol.
  • Must not be an IP address.
  • Must not include query parameters or has fragments.
  • Non-ASCII characters are normalised.
  • Must return a 2xx response, otherwise it will go through a retry cycle and eventually fail.
disabled
boolean

Indicates whether or not the Webhook is disabled. When set to true the webhook is disabled, and notifications for events associated with it will not be sent. If no value is provided, defaults to false.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
  • "events": [
    ],
  • "disabled": false
}

Delete Webhook

Deletes a Webhook by providing its ID.

Analytic events

  • WEBHOOK_DELETE_START
  • WEBHOOK_DELETE_SUCCESS
  • WEBHOOK_DELETE_FAIL
Authorizations:
path Parameters
id
required
string <uuid>

Webhook ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/webhooks/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Retrieve Webhook JWKs

Retrieves a list of Webhook JWKs (JSON Web Keys) from the tenant. These keys can be used to verify the HTTP signature and validate the integrity and authorship of generated Webhooks.

Authorizations:

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/webhooks/jwks' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Ecosystems

Retrieve all ecosystems

Retrieves a list of ecosystems.

Analytic events

  • ECOSYSTEM_RETRIEVE_LIST_START
  • ECOSYSTEM_RETRIEVE_LIST_SUCCESS
  • ECOSYSTEM_RETRIEVE_LIST_FAIL
Authorizations:
query Parameters
limit
number [ 1 .. 1000 ]
Default: 100

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Create ecosystem

Creates an ecosystem.

Analytic events

  • ECOSYSTEM_CREATE_START
  • ECOSYSTEM_CREATE_SUCCESS
  • ECOSYSTEM_CREATE_FAIL
Authorizations:
Request Body schema: application/json
name
string [ 1 .. 50 ] characters

The name of the ecosystem.

Responses

Request samples

Content type
application/json
{
  • "name": "My Ecosystem"
}

Response samples

Content type
application/json
{
  • "id": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  • "name": "My Ecosystem"
}

Retrieve ecosystem

Retrieves an ecosystem by its ID.

Analytic events

  • ECOSYSTEM_RETRIEVE_START
  • ECOSYSTEM_RETRIEVE_SUCCESS
  • ECOSYSTEM_RETRIEVE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  • "name": "My Ecosystem"
}

Update ecosystem

Updates an ecosystem by its ID.

Analytic events

  • ECOSYSTEM_UPDATE_START
  • ECOSYSTEM_UPDATE_SUCCESS
  • ECOSYSTEM_UPDATE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d

Responses

Request samples

curl -i -X PUT \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  • "name": "My Ecosystem"
}

Delete ecosystem

Deletes an ecosystem by its ID.

Analytic events

  • ECOSYSTEM_DELETE_START
  • ECOSYSTEM_DELETE_SUCCESS
  • ECOSYSTEM_DELETE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Participants

Retrieve participants

Retrieves a list of participants from the requested ecosystem.

Analytic events

  • ECOSYSTEM_PARTICIPANT_RETRIEVE_LIST_START
  • ECOSYSTEM_PARTICIPANT_RETRIEVE_LIST_SUCCESS
  • ECOSYSTEM_PARTICIPANT_RETRIEVE_LIST_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
query Parameters
limit
number [ 1 .. 1000 ]
Default: 100

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId/participants?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Create participant

Creates a participant in the requested ecosystem.

Analytic events

  • ECOSYSTEM_PARTICIPANT_CREATE_START
  • ECOSYSTEM_PARTICIPANT_CREATE_SUCCESS
  • ECOSYSTEM_PARTICIPANT_CREATE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
Request Body schema: application/json
name
required
string [ 1 .. 50 ] characters

Name to easily identify the participant.

required
object

Define the unique identifier that will be used by this participant to issue and/or verify credentials. Participants can have different identifiers for different credential profiles. Each participant must have at least one defined credential profile, and for each credential profile a participant can define exactly one unique identifier.

  • Credentials are only valid in the ecosystem if they include an identifier of an issuer that is a participant in the ecosystem.
  • Verification requests are only valid in the ecosystem if they include an identifier of a verifier that is a participant in the ecosystem.
  • For Mobile Credentials this must be the PEM of a valid IACA used by this participant to sign Mobile Credentials, as defined in annex B of ISO 18013-5. An exception to this aforementioned definition is that IACAs with a notBefore date in the future are considered valid.
isIssuer
boolean
Default: false

Indicates whether the participant is an issuer in the ecosystem (true) or not (false). When set to false, the participant will not be able to issue any valid credential types, even if it is added to an issuer policy. The default value is false, as this assigns the least privileges to the new participant.

isVerifier
boolean
Default: false

Indicates whether the created participant is a verifier in the ecosystem (true) or not (false). When set to false, the participant will not be able to verify any valid credential types, even if it is added to a verifier policy. The default value is false, as this assigns the least privileges to the new participant.

isIssuerConstrained
boolean
Default: true

Indicates whether the created participant is constrained to only issue specific types of valid credentials (true) or not (false). When set to false, the issuer can issue all valid credential types defined within the ecosystem, even if it is added to a more limited issuer policy. The default value is true, as this assigns the least privileges to the new participant.

isVerifierConstrained
boolean
Default: true

Indicates whether the created participant is constrained to only verify specific types of valid credentials (true) or not (false). When set to false, the verifier can verify all valid credential types defined within the ecosystem, even if it is added to a more limited verifier policy. The default value is true, as this assigns the least privileges to the new participant.

Responses

Request samples

Content type
application/json
{
  • "name": "My Participant",
  • "identifiers": {
    },
  • "isIssuer": false,
  • "isVerifier": false,
  • "isIssuerConstrained": true,
  • "isVerifierConstrained": true
}

Response samples

Content type
application/json
{
  • "id": "a24e391a-c27f-4b6e-9805-1ee7e03f3c58",
  • "ecosystemId": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  • "name": "My Participant",
  • "identifiers": {
    },
  • "isIssuer": false,
  • "isVerifier": false,
  • "isIssuerConstrained": true,
  • "isVerifierConstrained": true
}

Retrieve participant

Retrieves a participant from the requested ecosystem by its ID.

Analytic events

  • ECOSYSTEM_PARTICIPANT_RETRIEVE_START
  • ECOSYSTEM_PARTICIPANT_RETRIEVE_SUCCESS
  • ECOSYSTEM_PARTICIPANT_RETRIEVE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
participantId
required
string <uuid>

The UUID of the participant

Example: a24e391a-c27f-4b6e-9805-1ee7e03f3c58

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId/participants/:participantId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "a24e391a-c27f-4b6e-9805-1ee7e03f3c58",
  • "ecosystemId": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  • "name": "My Participant",
  • "identifiers": {
    },
  • "isIssuer": false,
  • "isVerifier": false,
  • "isIssuerConstrained": true,
  • "isVerifierConstrained": true
}

Update participant

Updates a participant in the requested ecosystem by its ID.

Analytic events

  • ECOSYSTEM_PARTICIPANT_UPDATE_START
  • ECOSYSTEM_PARTICIPANT_UPDATE_SUCCESS
  • ECOSYSTEM_PARTICIPANT_UPDATE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
participantId
required
string <uuid>

The UUID of the participant

Example: a24e391a-c27f-4b6e-9805-1ee7e03f3c58
Request Body schema: application/json
name
required
string [ 1 .. 50 ] characters

Name to easily identify the participant.

required
object

Define the unique identifier that will be used by this participant to issue and/or verify credentials. Participants can have different identifiers for different credential profiles. Each participant must have at least one defined credential profile, and for each credential profile a participant can define exactly one unique identifier.

  • Credentials are only valid in the ecosystem if they include an identifier of an issuer that is a participant in the ecosystem.
  • Verification requests are only valid in the ecosystem if they include an identifier of a verifier that is a participant in the ecosystem.
  • For Mobile Credentials this must be the PEM of a valid IACA used by this participant to sign Mobile Credentials, as defined in annex B of ISO 18013-5. An exception to this aforementioned definition is that IACAs with a notBefore date in the future are considered valid.
isIssuer
boolean
Default: false

Indicates whether the participant is an issuer in the ecosystem (true) or not (false). When set to false, the participant will not be able to issue any valid credential types, even if it is added to an issuer policy. The default value is false, as this assigns the least privileges to the new participant.

isVerifier
boolean
Default: false

Indicates whether the created participant is a verifier in the ecosystem (true) or not (false). When set to false, the participant will not be able to verify any valid credential types, even if it is added to a verifier policy. The default value is false, as this assigns the least privileges to the new participant.

isIssuerConstrained
boolean
Default: true

Indicates whether the created participant is constrained to only issue specific types of valid credentials (true) or not (false). When set to false, the issuer can issue all valid credential types defined within the ecosystem, even if it is added to a more limited issuer policy. The default value is true, as this assigns the least privileges to the new participant.

isVerifierConstrained
boolean
Default: true

Indicates whether the created participant is constrained to only verify specific types of valid credentials (true) or not (false). When set to false, the verifier can verify all valid credential types defined within the ecosystem, even if it is added to a more limited verifier policy. The default value is true, as this assigns the least privileges to the new participant.

Responses

Request samples

Content type
application/json
{
  • "name": "My Participant",
  • "identifiers": {
    },
  • "isIssuer": false,
  • "isVerifier": false,
  • "isIssuerConstrained": true,
  • "isVerifierConstrained": true
}

Response samples

Content type
application/json
{
  • "id": "a24e391a-c27f-4b6e-9805-1ee7e03f3c58",
  • "ecosystemId": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  • "name": "My Participant",
  • "identifiers": {
    },
  • "isIssuer": false,
  • "isVerifier": false,
  • "isIssuerConstrained": true,
  • "isVerifierConstrained": true
}

Delete participant

Deletes a participant in the requested ecosystem by its ID.

Analytic events

  • ECOSYSTEM_PARTICIPANT_DELETE_START
  • ECOSYSTEM_PARTICIPANT_DELETE_SUCCESS
  • ECOSYSTEM_PARTICIPANT_DELETE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
participantId
required
string <uuid>

The UUID of the participant

Example: a24e391a-c27f-4b6e-9805-1ee7e03f3c58

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId/participants/:participantId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Credential types

Create credential type

Creates a new credential type in the requested ecosystem.

Analytic events

  • ECOSYSTEM_CREDENTIAL_CREATE_START
  • ECOSYSTEM_CREDENTIAL_CREATE_SUCCESS
  • ECOSYSTEM_CREDENTIAL_CREATE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
Request Body schema: application/json
Any of
profile
required
string
Enum: "compact" "compact-semantic" "web-semantic"
type
required
string
name
required
string [ 1 .. 50 ] characters

The name of the credential

Responses

Request samples

Content type
application/json
{
  • "profile": "mobile",
  • "docType": "org.iso.18013.5.1",
  • "name": "Driver's Licence"
}

Response samples

Content type
application/json
{
  • "id": "49b6beb2-1006-4fb7-9284-7ec920475abe",
  • "ecosystemId": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  • "profile": "mobile",
  • "docType": "org.iso.18013.5.1",
  • "name": "Driver's Licence"
}

Retrieve credential types

Retrieves a list of credential types from the requested ecosystem.

Analytic events

  • ECOSYSTEM_CREDENTIAL_RETRIEVE_LIST_START
  • ECOSYSTEM_CREDENTIAL_RETRIEVE_LIST_SUCCESS
  • ECOSYSTEM_CREDENTIAL_RETRIEVE_LIST_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
query Parameters
limit
number [ 1 .. 1000 ]
Default: 100

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId/credentials?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Retrieve credential type

Retrieves a credential type from the requested ecosystem by its ID.

Analytic events

  • ECOSYSTEM_CREDENTIAL_RETRIEVE_START
  • ECOSYSTEM_CREDENTIAL_RETRIEVE_SUCCESS
  • ECOSYSTEM_CREDENTIAL_RETRIEVE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
credentialId
required
string <uuid>

The UUID of the credential

Example: 599bf148-d711-405a-a20b-9c8a87ac8850

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId/credentials/:credentialId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "49b6beb2-1006-4fb7-9284-7ec920475abe",
  • "ecosystemId": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  • "profile": "mobile",
  • "docType": "org.iso.18013.5.1",
  • "name": "Driver's Licence"
}

Delete credential type

Deletes a credential type from the requested ecosystem by its ID.

Analytic events

  • ECOSYSTEM_CREDENTIAL_DELETE_START
  • ECOSYSTEM_CREDENTIAL_DELETE_SUCCESS
  • ECOSYSTEM_CREDENTIAL_DELETE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
credentialId
required
string <uuid>

The UUID of the credential

Example: 599bf148-d711-405a-a20b-9c8a87ac8850

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId/credentials/:credentialId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Policy

Retrieve ecosystem policy

Retrieves an ecosystem policy by its ID.

Analytic events

  • ECOSYSTEM_POLICY_RETRIEVE_START
  • ECOSYSTEM_POLICY_RETRIEVE_SUCCESS
  • ECOSYSTEM_POLICY_RETRIEVE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
header Parameters
If-None-Match
string

The If-None-Match parameter enables caching. Specify the ETag of the latest retrieved policy version, so that the policy is only retrieved if it had changed since.

Accept-Encoding
string

Use the Accept-Encoding header to specify the supported content encodings.

Enum: "gzip" "deflate"

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId/policy' \
  -H 'Accept-Encoding: gzip' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'If-None-Match: string'

Response samples

Content type
application/json
{
  • "policyModifiedAt": "2023-10-17T00:00:00Z",
  • "credentials": [
    ],
  • "participants": [
    ]
}

Issuer Policies

Retrieve issuer policy

Retrieves an ecosystem issuer policy by its ID.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
header Parameters
If-None-Match
string

The If-None-Match parameter enables caching. Specify the ETag of the latest retrieved policy version, so that the policy is only retrieved if it had changed since.

Accept-Encoding
string

Use the Accept-Encoding header to specify the supported content encodings.

Enum: "gzip" "deflate"

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId/issuers' \
  -H 'Accept-Encoding: gzip' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'If-None-Match: string'

Response samples

Content type
application/json
{
  • "policyModifiedAt": "2023-10-17T00:00:00Z",
  • "credentials": [
    ],
  • "participants": [
    ]
}

Create issuer policy

Creates an issuer policy for the requested participant in the requested ecosystem.

Analytic events

  • ECOSYSTEM_ISSUER_POLICY_CREATE_START
  • ECOSYSTEM_ISSUER_POLICY_CREATE_SUCCESS
  • ECOSYSTEM_ISSUER_POLICY_CREATE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
participantId
required
string <uuid>

The UUID of the participant

Example: a24e391a-c27f-4b6e-9805-1ee7e03f3c58
Request Body schema: application/json
credentialId
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "credentialId": "599bf148-d711-405a-a20b-9c8a87ac8850"
}

Response samples

Content type
application/json
{
  • "id": "49b6beb2-1006-4fb7-9284-7ec920475abe",
  • "ecosystemId": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  • "profile": "mobile",
  • "docType": "org.iso.18013.5.1",
  • "name": "Driver's Licence"
}

Delete issuer policy

Deletes an issuer policy for the requested participant in the requested ecosystem by its ID.

Analytic events

  • ECOSYSTEM_ISSUER_POLICY_DELETE_START
  • ECOSYSTEM_ISSUER_POLICY_DELETE_SUCCESS
  • ECOSYSTEM_ISSUER_POLICY_DELETE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
participantId
required
string <uuid>

The UUID of the participant

Example: a24e391a-c27f-4b6e-9805-1ee7e03f3c58
credentialId
required
string <uuid>

The UUID of the credential

Example: 599bf148-d711-405a-a20b-9c8a87ac8850

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId/participants/:participantId/issuer/credentials/:credentialId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Verifier Policies

Retrieve verifier policy

Retrieves an ecosystem verifier policy by its ID.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
header Parameters
If-None-Match
string

The If-None-Match parameter enables caching. Specify the ETag of the latest retrieved policy version, so that the policy is only retrieved if it had changed since.

Accept-Encoding
string

Use the Accept-Encoding header to specify the supported content encodings.

Enum: "gzip" "deflate"

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId/verifiers' \
  -H 'Accept-Encoding: gzip' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'If-None-Match: string'

Response samples

Content type
application/json
{
  • "policyModifiedAt": "2023-10-17T00:00:00Z",
  • "credentials": [
    ],
  • "participants": [
    ]
}

Create verifier policy

Creates a verifier policy for the requested participant in the requested ecosystem.

Analytic events

  • ECOSYSTEM_VERIFIER_POLICY_CREATE_START
  • ECOSYSTEM_VERIFIER_POLICY_CREATE_SUCCESS
  • ECOSYSTEM_VERIFIER_POLICY_CREATE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
participantId
required
string <uuid>

The UUID of the participant

Example: a24e391a-c27f-4b6e-9805-1ee7e03f3c58
Request Body schema: application/json
credentialId
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "credentialId": "599bf148-d711-405a-a20b-9c8a87ac8850"
}

Response samples

Content type
application/json
{
  • "id": "49b6beb2-1006-4fb7-9284-7ec920475abe",
  • "ecosystemId": "87880d7e-a4d0-462e-8383-3f1e5e16865d",
  • "profile": "mobile",
  • "docType": "org.iso.18013.5.1",
  • "name": "Driver's Licence"
}

Delete verifier policy

Deletes a verifier policy for the requested participant in the requested ecosystem by its ID.

Analytic events

  • ECOSYSTEM_VERIFIER_POLICY_DELETE_START
  • ECOSYSTEM_VERIFIER_POLICY_DELETE_SUCCESS
  • ECOSYSTEM_VERIFIER_POLICY_DELETE_FAIL
Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

Example: 87880d7e-a4d0-462e-8383-3f1e5e16865d
participantId
required
string <uuid>

The UUID of the participant

Example: a24e391a-c27f-4b6e-9805-1ee7e03f3c58
credentialId
required
string <uuid>

The UUID of the credential

Example: 599bf148-d711-405a-a20b-9c8a87ac8850

Responses

Request samples

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v1/ecosystems/:ecosystemId/participants/:participantId/verifier/credentials/:credentialId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Compact Credentials

Sign a Compact Credential

Returns a signed Compact Credential generated from a provided valid payload.

The payload can include any number of custom claims, as Compact Credentials do not comply with any specific standard or specification.

Analytic events

  • CREDENTIAL_COMPACT_SIGN_START
  • CREDENTIAL_COMPACT_SIGN_SUCCESS
  • CREDENTIAL_COMPACT_SIGN_FAIL
Authorizations:
Request Body schema: application/json

Compact Credential payload to sign

required
object (CompactCredentialSignRequest)

CompactCredentialSignRequest

revocable
boolean
Default: false

When set to true, the created credential can later be revoked. When set to false, the credential cannot be revoked.

Responses

Request samples

Content type
application/json
{
  • "payload": {
    },
  • "revocable": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "encoded": "CSC:/1/2KCE3IQEJB5DCMSLN5KWKZABE2QFQRVDAF4CIZDJMQ5HOZLCHIYDGOJUFUYTENJNGIZTOLJVGIWTCMJQFZXGO4TPNMXGS33ENZQW2ZLEJJXWQ3QH3BAFB3LISHKGQ2KBJ6Q35NXZFD6LGZ2YIAYHZAKCF7NKTIUZUTZQ3PWDBALAWVRG5XL2H4P4WFK25X3Y5X5RTN7NOZUST67KLCEFS3EPXQU5KM7VUGOPXJLQ6K5U676PMQNWRZCZ",
  • "decoded": {
    }
}

Format a Compact Credential as a QR code

Returns a QR code representation of a Compact Credential from a provided encoded string representation of that credential.

Analytic events

  • CREDENTIAL_COMPACT_QRCODE_CREATE_START
  • CREDENTIAL_COMPACT_QRCODE_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_QRCODE_CREATE_FAIL
Authorizations:
Request Body schema: application/json
payload
required
string

String representation of the encoded Compact Credential.

width
number

Optionally specify the desired width of the output QR code. When no width is specified MATTR VII will generate a QR code with an optimised width based on the size of the payload. Maximal value is 1000px.

Responses

Request samples

Content type
application/json
{
  • "payload": "CSS:/1/2KCE3IQEJB5DCMSMGRKXI3IBE2QFSANKVACBUYQYB2HQKGTCDAHI6BQ2MIMA5DYBPAUWI2L...",
  • "width": 250
}

Response samples

Content type
application/json
Example
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Format a Compact Credential as a PDF

Returns a PDF representation of a provided Compact Credential based on an existing PDF template.

The request will fail if the provided credential isn't valid or has expired.

Analytic events

  • CREDENTIAL_COMPACT_PDF_CREATE_START
  • CREDENTIAL_COMPACT_PDF_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_PDF_CREATE_FAIL
Authorizations:
Request Body schema: application/json

Credential payload

templateId
string non-empty

Use the ID element of the PDF template to be used to format this credential.

payload
string [ 1 .. 1024 ] characters

String payload representation of the encoded Compact Credential.

Responses

Request samples

Content type
application/json
{
  • "templateId": "4eea7654-d4c5-4eba-bd7a-5ca334d54725",
  • "payload": "{payload}"
}

Format a Compact Credential as an Apple Pass

Returns an Apple Pass representation of a provided Compact Credential based on an existing Apple Pass template.

The request will fail if the provided credential isn't valid or has expired.

Analytic events

  • CREDENTIAL_COMPACT_APPLE_PASS_CREATE_START
  • CREDENTIAL_COMPACT_APPLE_PASS_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_APPLE_PASS_CREATE_FAIL
Authorizations:
Request Body schema: application/json
templateId
string non-empty

Use the id of the template to be used to format this credential.

payload
string

String payload representation of the encoded Compact Credential.

Responses

Request samples

Content type
application/json
{
  • "templateId": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "payload": "{payload}"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Format a Compact Credential as a Google Pass

Returns a Google Pass representation of a provided Compact Credential based on an existing Google Pass template.

The request will fail if the provided credential isn't valid or has expired.

Analytic events

  • CREDENTIAL_COMPACT_GOOGLE_PASS_CREATE_START
  • CREDENTIAL_COMPACT_GOOGLE_PASS_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_GOOGLE_PASS_CREATE_FAIL
Authorizations:
Request Body schema: application/json
templateId
string non-empty

Use the id of the template to be used to format this credential.

payload
string

String payload representation of the encoded Compact Credential.

Responses

Request samples

Content type
application/json
{
  • "templateId": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "payload": "{payload}"
}

Response samples

Content type
application/json

Compact Semantic Credentials

Sign a Compact Semantic Credential

Returns a signed Compact Semantic Credential generated from a provided valid payload.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_SIGN_START
  • CREDENTIAL_COMPACT_SEMANTIC_SIGN_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_SIGN_FAIL
Authorizations:
Request Body schema: application/json

Compact Semantic Credential payload to sign

required
object (CompactSemanticCredentialSignRequest)

CompactSemanticCredentialSignRequest

revocable
boolean
Default: false

When set to true, the created credential can later be revoked. When set to false, the credential cannot be revoked.

Responses

Request samples

Content type
application/json
{
  • "payload": {
    },
  • "revocable": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "encoded": "CSS:/1/BASE_32_ENCODED_PAYLOAD",
  • "decoded": {}
}

Format a Compact Semantic Credential as a QR code

Returns a QR code representation of a Compact Semantic Credential from a provided encoded string representation of that credential.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_QRCODE_CREATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_QRCODE_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_QRCODE_CREATE_FAIL
Authorizations:
Request Body schema: application/json
payload
required
string

String representation of the encoded Compact Credential.

width
number

Optionally specify the desired width of the output QR code. When no width is specified MATTR VII will generate a QR code with an optimised width based on the size of the payload. Maximal value is 1000px.

Responses

Request samples

Content type
application/json
{
  • "payload": "CSS:/1/2KCE3IQEJB5DCMSMGRKXI3IBE2QFSANKVACBUYQYB2HQKGTCDAHI6BQ2MIMA5DYBPAUWI2L...",
  • "width": 250
}

Response samples

Content type
application/json
Example