Learn
latest
latest
v2.2.5
v2.1.0
v2.0.0
v1.0.1
v0
management

MATTR VII API (v2.3.1)

Download OpenAPI specification:Download

E-mail: support@mattr.global

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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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
Verification successful
Verification successful
Verification failed
{
  • "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:
bearerAuth
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
Encrypt credential offer
Encrypt credential offer
Encrypt credential
{
  • "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:
bearerAuth
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:
bearerAuth
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": [
    ]
}

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",
  • "audience": "https://learn.vii.au01.mattr.global",
  • "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:
bearerAuth
Request Body schema:
application/json
application/json
application/xml

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
application/json
application/json
application/xml
{}

Response samples

Content type
application/json
{
  • "name": "Example Corp",
  • "logoUrl": "https://cdn.example.com/logo.jpg",
  • "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:
bearerAuth

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",
  • "logoUrl": "https://cdn.example.com/logo.icon",
  • "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:
bearerAuth

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:
bearerAuth
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",
  • "logoUrl": "https://cdn.example.com/logo.icon",
  • "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:
bearerAuth

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:
bearerAuth
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
Create did:web
Create did:web
Create did:key
{
  • "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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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": [
    ]
}

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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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
Inbox ID not UUID format
Inbox ID not UUID format
Message ID not UUID format
{
  • "code": "BadRequest",
  • "message": "Validation Error",
  • "details": [
    ]
}

Webhooks

Create Webhook

Creates a new webhook for this tenant.

Analytic events

  • WEBHOOK_CREATE_START
  • WEBHOOK_CREATE_SUCCESS
  • WEBHOOK_CREATE_FAIL
Authorizations:
bearerAuth
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": [
    ],
  • "url": "https://example.com",
  • "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:
bearerAuth
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:
bearerAuth
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": [
    ],
  • "url": "https://example.com",
  • "disabled": false
}

Update Webhook

Updates an existing Webhook by providing its ID.

Analytic events

  • WEBHOOK_UPDATE_START
  • WEBHOOK_UPDATE_SUCCESS
  • WEBHOOK_UPDATE_FAIL
Authorizations:
bearerAuth
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": [
    ],
  • "url": "https://example.com",
  • "disabled": false
}

Delete Webhook

Deletes a Webhook by providing its ID.

Analytic events

  • WEBHOOK_DELETE_START
  • WEBHOOK_DELETE_SUCCESS
  • WEBHOOK_DELETE_FAIL
Authorizations:
bearerAuth
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:
bearerAuth

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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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": {
    }
}

Delete Compact Credential metadata

Deletes all credential metadata from the tenant for a specific credential by providing its ID. If the credential was set to be revocable, it will be permanently revoked upon metadata deletion.

Note that only metadata of revocable credentials or credentials issued via the OpenID4VCI flow is saved.

Deleted metadata cannot be recovered.

Authorizations:
bearerAuth
path Parameters
id
required
string

Credential ID

Responses

Request samples 

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

Response samples

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

Verify a Compact Credential

Verify a Compact Credential by providing the encoded payload and specifying verification options.

You can provide a valid Compact Credential as either an encoded string or a QR code in a PDF document or an image file.

Standard checks performed on all verification requests:

  • Conformance of the string and encoded data. All string representations of Compact Credentials must be prefixed with CSC/1.
  • Decoded payload structure is a valid Compact Credential.
  • Issuer DID can be used to resolve its did.json document.
  • Public key from issuer's did.json document validates the proof signature, confirming the credential has not been tampered with.

Optional parameter checks:

  • Credential was issued by a trusted issuer.
  • Current time is after the beginning of the credential validity period.
  • Current time is not after the end of the credential validity period.
  • Credential has not been revoked.

Analytic events

  • CREDENTIAL_COMPACT_VERIFY_START
  • CREDENTIAL_COMPACT_VERIFY_SUCCESS
  • CREDENTIAL_COMPACT_VERIFY_FAIL
Authorizations:
bearerAuth
Request Body schema:
application/json
application/json
multipart/form-data
payload
required
string

The Compact Credential to verify, represented as an encoded string.

trustedIssuers
Array of strings

When you include issuers' DIDs in this array, credentials will only be verified if their iss value matches one of these DIDs. You can include multiple trusted issuers, separated by commas.

assertValidFrom
boolean
Default: true

MATTR VII validates the credential's nbf (not before) field by default, so that credentials that have a future nbf date will not be verified. When this field is set to false, credentials can be verified even when their nbf date is in the future.

assertValidUntil
boolean
Default: true

MATTR VII validates the credential's exp (expiry) field by default, so that expired credentials will not be verified. When this field is set to false, credentials can be verified even when their exp date has passed.

checkRevocation
boolean
Default: true

MATTR VII checks the credential revocation status by default, so that revoked credentials will not be verified. When this field is set to false, credentials can be verified even when they had been revoked.

Responses

Request samples

Content type
application/json
application/json
multipart/form-data
{
  • "payload": "CSC:/1/2KCE3IQEJB5DCMSLN5KWKZABE2QFQRVDAF4CIZDJMQ5HOZLCHIYDGOJUFUYTENJNGIZTOLJVGIWTCMJQFZXGO4TPNMXGS33ENZQW2ZLEJJXWQ3QH3BAFB3LISHKGQ2KBJ6Q35NXZFD6LGZ2YIAYHZAKCF7NKTIUZUTZQ3PWDBALAWVRG5XL2H4P4WFK25X3Y5X5RTN7NOZUST67KLCEFS3EPXQU5KM7VUGOPXJLQ6K5U676PMQNWRZCZ",
  • "trustedIssuers": [
    ],
  • "assertValidFrom": true,
  • "assertValidUntil": true,
  • "checkRevocation": true
}

Response samples

Content type
application/json
{
  • "verified": true,
  • "decoded": {
    },
  • "error": {
    }
}

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:
bearerAuth
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
Payload is not string
Payload is not string
The payload does not belong to compact credential profile
The amount of data is too big to be stored in a QR Code
The generated QR Code is larger than the provided width
{
  • "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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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 Credentials configuration

Create a Compact Credential configuration

Creates a new Compact Credential configuration, a specific set of rules and parameters that are used to create and validate a particular type of verifiable credential. These rules and parameters define how the credential is structured and what data it contains when issued.

Analytic events

  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_CREATE_START
  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The Credential Configuration payload

type
required
string [ 1 .. 1024 ] characters

Used to differentiate between different Compact/Compact Semantic credential configurations on your tenant. Thus, its value must:

  • Be unique across all Compact/Semantic compact credential configurations on your tenant.
  • Not be VerifiableCredential.
required
object

This is where you specify how to map claims (user attributes) into issued credentials. Each field in the object corresponds to a claim in the issued credential, and contains one or more from the following attributes:

  • mapFrom: References the path in the user object where the claim is available.
    • When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g. mapFrom: "claims['https://example.com/claim-name']").
    • mapForm is optional when defaultValue is provided, as the latter will be used for all issued credentials. This is referred to as a static claim.
  • defaultValue: Indicates what value is used if required is set to false (field is optional) and no value is provided by the claims source. When defaultValue is provided, mapFrom is optional.
  • required: Indicates whether the claim is required (default: false). When a required claim cannot be retrieved and no defaultValue is available, credential issuance will fail.
  • Example source context object*
    {
 "claims": {
   "given_name": "Jamie",
   "family_name": "Doe",
   "address": {
     "formatted": "116-118 Quay Street, Auckland CBD, Auckland 1010"
   }
 },
 "authenticationProvider": {
   "subjectId": "6d3aab7d-73af-5f61-b47c-109ef6f7558c",
   "url": "https://accounts.google.com"
 }
}
revocable
boolean
Default: true

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

claimSourceId
string <uuid>

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

object

Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds.

Responses

Request samples

Content type
application/json
{
  • "type": "CourseCredential",
  • "claimMappings": {},
  • "revocable": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "type": "CourseCredential",
  • "claimMappings": {},
  • "revocable": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Retrieve all Compact Credential configurations

Returns a list of all Comapct Credential configurations from your tenant.

Analytic events

  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_START
  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned entries, default 100

Example: limit=2
cursor
string

Starting point for the range of entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
type
string

The optional credential type to filter on

Example: type=AlumniCredential

Responses

Request samples 

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

Response samples

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

Retrieve a Compact Credential configuration

Returns a Compact Credential Configuration by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_RETRIEVE_START
  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Unique identifier for the Compact Credential configuration.

Example: 3948c40e-6e19-4ffc-933c-91f643f24264

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "type": "CourseCredential",
  • "claimMappings": {},
  • "revocable": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Update a Compact Credential configuration

Updates an existing Compact Credential configuration by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_UPDATE_START
  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_UPDATE_SUCCESS
  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Unique identifier for the Compact Credential configuration.

Example: 3948c40e-6e19-4ffc-933c-91f643f24264
Request Body schema: application/json

Update a Compact Credential configuration

type
required
string [ 1 .. 1024 ] characters

Used to differentiate between different Compact/Compact Semantic credential configurations on your tenant. Thus, its value must:

  • Be unique across all Compact/Semantic compact credential configurations on your tenant.
  • Not be VerifiableCredential.
required
object

This is where you specify how to map claims (user attributes) into issued credentials. Each field in the object corresponds to a claim in the issued credential, and contains one or more from the following attributes:

  • mapFrom: References the path in the user object where the claim is available.
    • When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g. mapFrom: "claims['https://example.com/claim-name']").
    • mapForm is optional when defaultValue is provided, as the latter will be used for all issued credentials. This is referred to as a static claim.
  • defaultValue: Indicates what value is used if required is set to false (field is optional) and no value is provided by the claims source. When defaultValue is provided, mapFrom is optional.
  • required: Indicates whether the claim is required (default: false). When a required claim cannot be retrieved and no defaultValue is available, credential issuance will fail.
  • Example source context object*
    {
 "claims": {
   "given_name": "Jamie",
   "family_name": "Doe",
   "address": {
     "formatted": "116-118 Quay Street, Auckland CBD, Auckland 1010"
   }
 },
 "authenticationProvider": {
   "subjectId": "6d3aab7d-73af-5f61-b47c-109ef6f7558c",
   "url": "https://accounts.google.com"
 }
}
revocable
boolean
Default: true

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

claimSourceId
string <uuid>

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

object

Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds.

Responses

Request samples

Content type
application/json
{
  • "type": "CourseCredential",
  • "claimMappings": {},
  • "revocable": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "type": "CourseCredential",
  • "claimMappings": {},
  • "revocable": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Delete a Compact Credential configuration

Deletes an exising Compact Credential configuration by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_DELETE_START
  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_DELETE_SUCCESS
  • CREDENTIAL_COMPACT_CREDENTIAL_CONFIGURATION_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Unique identifier for the Compact Credential configuration.

Example: 3948c40e-6e19-4ffc-933c-91f643f24264

Responses

Request samples 

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

Response samples

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

Compact Credentials revocation

Retrieve all Compact Credential revocation lists

Returns a list of all Compact Credential revocation lists on the tenant.

Analytic events

  • CREDENTIAL_COMPACT_REVOCATION_LISTS_RETRIEVE_START
  • CREDENTIAL_COMPACT_REVOCATION_LISTS_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_REVOCATION_LISTS_RETRIEVE_FAIL
Authorizations:
bearerAuth

Responses

Request samples 

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

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve Compact Credential revocation list

Returns a Compact Credential revocation list by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_REVOCATION_RETRIEVE_START
  • CREDENTIAL_COMPACT_REVOCATION_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_REVOCATION_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
listId
required
string

The unique identifier of the Revocation List you wish to retrieve.

Responses

Request samples 

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

Update Compact Credential revocation status

Updates the credential status as revoked (invalid) or unrevoked (valid).

Analytic events

  • CREDENTIAL_COMPACT_REVOCATION_SET_STATUS_START
  • CREDENTIAL_COMPACT_REVOCATION_SET_STATUS_SUCCESS
  • CREDENTIAL_COMPACT_REVOCATION_SET_STATUS_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Unique credential identifier.

Request Body schema: application/json

Update revocation status

isRevoked
required
boolean

When set to true the credential will be revoked. When set to false, the credential will be unrevoked.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "isRevoked": true
}

Retrieve Compact Credential revocation status

Retrieve the revocation status of a Compact Credential by providing its ID.

Authorizations:
bearerAuth
path Parameters
id
required
string

Unique credential identifier.

Responses

Request samples 

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

Response samples

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

Compact Credentials PDF templates

Create a PDF template

Creates a Compact Credential PDF template based on a provided .zip file. Refer to our PDF template design tutorial for more information on how to design a template and structure the .zip file.

Analytic events

  • CREDENTIAL_COMPACT_PDF_TEMPLATE_CREATE_START
  • CREDENTIAL_COMPACT_PDF_TEMPLATE_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_PDF_TEMPLATE_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/zip
string <binary>

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact/pdf/templates' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/zip'

Response samples

Content type
application/json
{
  • "id": "4eea7654-d4c5-4eba-bd7a-5ca334d54725",
  • "name": "Certificate of participation",
  • "fileName": "certificate_of_participation",
  • "fonts": [
    ],
  • "metadata": {
    },
  • "fields": [
    ]
}

Retrieve all PDF templates

Retrieves a list of all Compact Credential PDF templates available on the tenant.

Analytic events

  • CREDENTIAL_COMPACT_PDF_TEMPLATE_RETRIEVE_LIST_START
  • CREDENTIAL_COMPACT_PDF_TEMPLATE_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_COMPACT_PDF_TEMPLATE_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
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/v2/credentials/compact/pdf/templates?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "nextCursor": "0ecdcb57-ef2b-4aa1-be34-695c2d9d9486",
  • "data": [
    ]
}

Update a PDF template

Update an existing Compact Credential PDF template based on a provided .zip file. Refer to our PDF template design tutorial for more information on how to design a template and structure the .zip file.

Analytic events

  • CREDENTIAL_COMPACT_PDF_TEMPLATE_UPDATE_START
  • CREDENTIAL_COMPACT_PDF_TEMPLATE_UPDATE_SUCCESS
  • CREDENTIAL_COMPACT_PDF_TEMPLATE_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

PDF template ID

Request Body schema: application/zip
string <binary>

Responses

Request samples 

curl -i -X PUT \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact/pdf/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/zip'

Response samples

Content type
application/json
{
  • "id": "4eea7654-d4c5-4eba-bd7a-5ca334d54725",
  • "name": "Certificate of participation",
  • "fileName": "certificate_of_participation",
  • "fonts": [
    ],
  • "metadata": {
    },
  • "fields": [
    ]
}

Retrieve a PDF template

Retrieves an existing Compact Credential PDF template using its ID.

Analytic events

  • CREDENTIAL_COMPACT_PDF_TEMPLATE_RETRIEVE_START
  • CREDENTIAL_COMPACT_PDF_TEMPLATE_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_PDF_TEMPLATE_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

PDF template ID

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "4eea7654-d4c5-4eba-bd7a-5ca334d54725",
  • "name": "Certificate of participation",
  • "fileName": "certificate_of_participation",
  • "fonts": [
    ],
  • "metadata": {
    },
  • "fields": [
    ]
}

Delete a PDF template

Delete an existing PDF template by providing its ID

Analytic events

  • CREDENTIAL_COMPACT_PDF_TEMPLATE_DELETE_START
  • CREDENTIAL_COMPACT_PDF_TEMPLATE_DELETE_SUCCESS
  • CREDENTIAL_COMPACT_PDF_TEMPLATE_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

PDF Template ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact/pdf/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Compact Credentials Apple Pass templates

Create an Apple Pass template

Creates an Apple Pass template based on the provided .zip file. Refer to our Design an Apple Pass template tutorial for more information on how to design the template and how to structure the .zip file.

The Apple Pass template uses the official Apple Pass bundle structure.

Analytic events

  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_CREATE_START
  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
template
required
string <binary>

Includes your template files.

name
required
string [ 1 .. 1024 ] characters

Insert a name to identify this Apple digital pass template.

fileName
required
string [ 1 .. 100 ] characters

Insert the file name that will be assigned to Apple digital passes created from this template. Must only include alphanumeric characters, ''_'', or ''-'', and end with .pkpass.

teamIdentifier
required
string

The Team ID for the Apple Developer Program account that registered the pass type identifier.

passTypeIdentifier
required
string

The pass type identifier that’s registered with Apple. The value must be the same as the distribution certificate used to sign the pass.

wwdr
required
string

Apple G1 or G4 worldwide developer relations intermediate certificate.

signerCert
required
string

Apple pass signer certificate.

signerKey
required
string

The encrypted key of the Apple pass signer certificate.

signerKeyPassphrase
required
string

Passphrase for the encrypted key.

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact/digitalpass/apple/templates' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F fileName=certificate_of_participation.pkpass \
  -F 'name=Certificate of participation' \
  -F passTypeIdentifier=pass.myproject.participation.pk \
  -F signerCert=string \
  -F signerKey=string \
  -F signerKeyPassphrase=string \
  -F teamIdentifier=GH5P43ABC \
  -F template=string \
  -F wwdr=string

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Retrieve all Apple Pass templates

Retrieves a list of all Apple Pass template available on the tenant.

Analytic events

  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_RETRIEVE_LIST_START
  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
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/v2/credentials/compact/digitalpass/apple/templates?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Update an Apple Pass template

Updates an existing Apple Pass template by providing its ID and a .zip file. Refer to our Design an Apple Pass template tutorial for more information on how to design the template and how to structure the .zip file.

Analytic events

  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_UPDATE_START
  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_UPDATE_SUCCESS
  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Apple Pass template ID

Request Body schema: multipart/form-data
template
required
string <binary>

Includes your template files.

name
required
string [ 1 .. 1024 ] characters

Insert a name to identify this Apple digital pass template.

fileName
required
string [ 1 .. 100 ] characters

Insert the file name that will be assigned to Apple digital passes created from this template. Must only include alphanumeric characters, ''_'', or ''-'', and end with .pkpass.

teamIdentifier
required
string

The Team ID for the Apple Developer Program account that registered the pass type identifier.

passTypeIdentifier
required
string

The pass type identifier that’s registered with Apple. The value must be the same as the distribution certificate used to sign the pass.

wwdr
required
string

Apple G1 or G4 worldwide developer relations intermediate certificate.

signerCert
required
string

Apple pass signer certificate.

signerKey
required
string

The encrypted key of the Apple pass signer certificate.

signerKeyPassphrase
required
string

Passphrase for the encrypted key.

Responses

Request samples 

curl -i -X PUT \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact/digitalpass/apple/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F fileName=certificate_of_participation.pkpass \
  -F 'name=Certificate of participation' \
  -F passTypeIdentifier=pass.myproject.participation.pk \
  -F signerCert=string \
  -F signerKey=string \
  -F signerKeyPassphrase=string \
  -F teamIdentifier=GH5P43ABC \
  -F template=string \
  -F wwdr=string

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Retrieve an Apple Pass template

Retrieves an existing Apple Pass template by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_RETRIEVE_START
  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Apple Pass template ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact/digitalpass/apple/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Delete an Apple Pass template

Deletes an existing Apple Pass template by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_DELETE_START
  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_DELETE_SUCCESS
  • CREDENTIAL_COMPACT_APPLE_PASS_TEMPLATE_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Apple Pass template ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact/digitalpass/apple/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Compact Credentials Google Pass templates

Create a Google Pass template

Creates a Google Pass template based on the provided .zip file. Refer to our Design a Google Pass template tutorial for more information on how to design the template and how to structure the .zip file.

Analytic events

  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_CREATE_START
  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
template
required
string <binary>

Includes your template files.

name
required
string [ 1 .. 1024 ] characters

Insert a name to identify this Google Pass template.

issuerId
required
string

Google Wallet Pass signer issuer ID.

serviceAccountClientEmail
required
string

Email address of the Google Cloud Platform service account for accessing the Google Pay Passes API.

serviceAccountPrivateKey
required
string

Private key PEM of the Google Cloud Platform service account.

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact/digitalpass/google/templates' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F issuerId=3388000000012346000 \
  -F 'name=Certificate of participation' \
  -F serviceAccountClientEmail=app-user@myproject.iam.gserviceaccount.com \
  -F serviceAccountPrivateKey=string \
  -F template=string

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Retrieve all Google Pass templates

Retrieves a list of all Google Pass templates available on your tenant.

Analytic events

  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_RETRIEVE_LIST_START
  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
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/v2/credentials/compact/digitalpass/google/templates?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Update a Google Pass template

Updates a existing Google Pass template by providing its ID and a .zip file. Refer to our Design a Google Pass template tutorial for more information on how to design the template and how to structure the .zip file.

Analytic events

  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_UPDATE_START
  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_UPDATE_SUCCESS
  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Google Pass template ID

Request Body schema: multipart/form-data
template
required
string <binary>

Includes your template files.

name
required
string [ 1 .. 1024 ] characters

Insert a name to identify this Google Pass template.

issuerId
required
string

Google Wallet Pass signer issuer ID.

serviceAccountClientEmail
required
string

Email address of the Google Cloud Platform service account for accessing the Google Pay Passes API.

serviceAccountPrivateKey
required
string

Private key PEM of the Google Cloud Platform service account.

Responses

Request samples 

curl -i -X PUT \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact/digitalpass/google/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F issuerId=3388000000012346000 \
  -F 'name=Certificate of participation' \
  -F serviceAccountClientEmail=app-user@myproject.iam.gserviceaccount.com \
  -F serviceAccountPrivateKey=string \
  -F template=string

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Retrieve a Google Pass template

Retrieves an existing Google Pass template by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_RETRIEVE_START
  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Google Pass template ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact/digitalpass/google/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Delete a Google Pass template

Deletes an existing Google Pass template by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_DELETE_START
  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_DELETE_SUCCESS
  • CREDENTIAL_COMPACT_GOOGLE_PASS_TEMPLATE_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Google Pass template ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact/digitalpass/google/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

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:
bearerAuth
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": {}
}

Verify a Compact Semantic Credential

Verify a Compact Semantic Credential by providing the encoded payload and specifying verification options.

You can provide a valid Compact Semantic Credential as either an encoded string or a QR code in a PDF document or an image file.

Standard checks performed on all verification requests:

  • Conformance of the string and encoded data. All string representations of Compact Credentials must be prefixed with CSC/1.
  • Decoded payload CWT structure and attributes can be validated.
  • Remote context schema can be resolved and validate claims can be dereferenced.
  • Issuer DID can be used to resolve its did.json document.
  • Public key from issuer's did.json document validates the proof signature, confirming the credential has not been tampered with.

Optional parameter checks:

  • Credential was issued by a trusted issuer.
  • Current time is after the beginning of the credential validity period.
  • Current time is not after the end of the credential validity period.
  • Credential has not been revoked.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_VERIFY_START
  • CREDENTIAL_COMPACT_SEMANTIC_VERIFY_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_VERIFY_FAIL
Authorizations:
bearerAuth
Request Body schema:
application/json
application/json
multipart/form-data
payload
required
string

The Compact Semantic Credential to verify, represented as an encoded string.

trustedIssuers
Array of strings

When you include issuers' DIDs in this array, credentials will only be verified if their iss value matches one of these DIDs. You can include multiple trusted issuers, separated by commas.

assertValidFrom
boolean
Default: true

MATTR VII validates the credential's nbf (not before) field by default, so that credentials that have a future nbf date will not be verified. When this field is set to false, credentials can be verified even when their nbf date is in the future.

assertValidUntil
boolean
Default: true

MATTR VII validates the credential's exp (expiry) field by default, so that expired credentials will not be verified. When this field is set to false, credentials can be verified even when their exp date has passed.

checkRevocation
boolean
Default: true

MATTR VII checks the credential revocation status by default, so that revoked credentials will not be verified. When this field is set to false, credentials can be verified even when they had been revoked.

Responses

Request samples

Content type
application/json
application/json
multipart/form-data
{
  • "payload": "CSS:/1/2KCE3IQEJB5DCMSLN5KWKZABE2QFRMFEAF4CIZDJMQ5HOZLCHIYDGOJUFUYTENJNGIZTOLJVGIWTCMJQFZXGO4TPNMXGS33COZR2G2CAMNXW45DFPB2IC6BGNB2HI4DTHIXS653XO4XHOMZON5ZGOLZSGAYTQL3DOJSWIZLOORUWC3DTF53DCZDUPFYGLALUKZSXE2LGNFQWE3DFINZGKZDFNZ2GSYLMOFRXEZLEMVXHI2LBNRJXKYTKMVRXJILENZQW2ZLEJJXWQ3QH3BAFAW2MIRFQDICFCSNL5EIX4IISCEIFDJRFHCRRLBALWFYDLUVEKXHERNWHUDGJI3DDNNXSFWIRHUASBHGB2I7UHGPZMJEB3SMOFMBL3PABL5HUFSQLLGNE7YRKSAM3OAQN7F4LG365HL67BU",
  • "trustedIssuers": [
    ],
  • "assertValidFrom": true,
  • "assertValidUntil": true,
  • "checkRevocation": true
}

Response samples

Content type
application/json
Example
Issuer not trusted
Issuer not trusted
Issuer public key invalid
Signature invalid
Expired
NotActive
Revoked
{
  • "verified": false,
  • "reason": [
    ],
  • "decoded": {}
}

Delete Compact Semantic Credential metadata

Deletes all credential metadata from the tenant for a specific credential by providing its ID. If the credential was set to be revocable, it will be permanently revoked upon metadata deletion.

Note that only metadata of revocable credentials or credentials issued via the OpenID4VCI flow is saved.

Deleted metadata cannot be recovered.

Authorizations:
bearerAuth
path Parameters
id
required
string

Credential ID

Responses

Request samples 

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

Response samples

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

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:
bearerAuth
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
Payload is not string
Payload is not string
The payload does not belong to compact semantic credential profile
The amount of data is too big to be stored in a QR Code
The generated QR Code is larger than the provided width
{
  • "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_SEMANTIC_PDF_CREATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The 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 Semantic Credential as an Apple Pass

Returns an Apple Pass representation of a provided Compact Semantic 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_SEMANTIC_APPLE_PASS_CREATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_CREATE_FAIL
Authorizations:
bearerAuth
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 Semantic 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_SEMANTIC_GOOGLE_PASS_CREATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_CREATE_FAIL
Authorizations:
bearerAuth
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 configuration

Create a Compact Semantic Credential Configuration

Creates a new Compact Semantic Credential configuration, a specific set of rules and parameters that are used to create and validate a particular type of verifiable credential. These rules and parameters define how the credential is structured and what data it contains when issued.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The Credential Configuration payload

type
required
string [ 1 .. 1024 ] characters

Used to differentiate between different Compact/Compact Semantic credential configurations on your tenant. Thus, its value must:

  • Be unique across all Compact/Semantic compact credential configurations on your tenant.
  • Not be VerifiableCredential. type: string
required
object

This is where you specify how to map claims (user attributes) into issued credentials. Each field in the object corresponds to a claim in the issued credential, and contains one or more from the following attributes:

  • mapFrom: References the path in the user object where the claim is available.
    • When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g. mapFrom: "claims['https://example.com/claim-name']").
    • mapForm is optional when defaultValue is provided, as the latter will be used for all issued credentials. This is referred to as a static claim.
  • defaultValue: Indicates what value is used if required is set to false (field is optional) and no value is provided by the claims source. When defaultValue is provided, mapFrom is optional.
  • required: Indicates whether the claim is required (default: false). When a required claim cannot be retrieved and no defaultValue is available, credential issuance will fail.
  • Example source context object*
    {
 "claims": {
   "given_name": "Jamie",
   "family_name": "Doe",
   "address": {
     "formatted": "116-118 Quay Street, Auckland CBD, Auckland 1010"
   }
 },
 "authenticationProvider": {
   "subjectId": "6d3aab7d-73af-5f61-b47c-109ef6f7558c",
   "url": "https://accounts.google.com"
 }
}
revocable
boolean
Default: true

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

claimSourceId
string <uuid>

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

object

Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds.

Responses

Request samples

Content type
application/json
{
  • "type": "CourseCredential",
  • "claimMappings": {},
  • "revocable": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "type": "CourseCredential",
  • "claimMappings": {},
  • "revocable": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Retrieve all Compact Semantic Credential configurations

Returns a list of all Comapct Semantic Credential configurations from your tenant.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_START
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned entries, default 100

Example: limit=2
cursor
string

Starting point for the range of entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
type
string

The optional credential type to filter on

Example: type=AlumniCredential

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/configurations?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h&type=AlumniCredential' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Retrieve a Compact Semantic Credential Configuration

Returns a Compact Semantic Credential Configuration by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_START
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Unique identifier for the Compact Semantic Credential configuration.

Example: 3948c40e-6e19-4ffc-933c-91f643f24264

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "type": "CourseCredential",
  • "claimMappings": {},
  • "revocable": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Update a Compact Semantic Credential configuration

Updates an existing Compact Semantic Credential configuration by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Unique identifier for the Compact Semantic Credential configuration.

Example: 3948c40e-6e19-4ffc-933c-91f643f24264
Request Body schema: application/json

Update a Credential Configuration

type
required
string [ 1 .. 1024 ] characters

Used to differentiate between different Compact/Compact Semantic credential configurations on your tenant. Thus, its value must:

  • Be unique across all Compact/Semantic compact credential configurations on your tenant.
  • Not be VerifiableCredential. type: string
required
object

This is where you specify how to map claims (user attributes) into issued credentials. Each field in the object corresponds to a claim in the issued credential, and contains one or more from the following attributes:

  • mapFrom: References the path in the user object where the claim is available.
    • When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g. mapFrom: "claims['https://example.com/claim-name']").
    • mapForm is optional when defaultValue is provided, as the latter will be used for all issued credentials. This is referred to as a static claim.
  • defaultValue: Indicates what value is used if required is set to false (field is optional) and no value is provided by the claims source. When defaultValue is provided, mapFrom is optional.
  • required: Indicates whether the claim is required (default: false). When a required claim cannot be retrieved and no defaultValue is available, credential issuance will fail.
  • Example source context object*
    {
 "claims": {
   "given_name": "Jamie",
   "family_name": "Doe",
   "address": {
     "formatted": "116-118 Quay Street, Auckland CBD, Auckland 1010"
   }
 },
 "authenticationProvider": {
   "subjectId": "6d3aab7d-73af-5f61-b47c-109ef6f7558c",
   "url": "https://accounts.google.com"
 }
}
revocable
boolean
Default: true

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

claimSourceId
string <uuid>

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

object

Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds.

Responses

Request samples

Content type
application/json
{
  • "type": "CourseCredential",
  • "claimMappings": {},
  • "revocable": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "type": "CourseCredential",
  • "claimMappings": {},
  • "revocable": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Delete a Compact Semantic Credential configuration

Deletes an exising Compact Semantic Credential configuration by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_START
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Unique identifier for the Compact Semantic Credential configuration.

Example: 3948c40e-6e19-4ffc-933c-91f643f24264

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/configurations/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Compact Semantic Credentials revocation

Retrieve all Compact Semantic Credential revocation lists

Returns a list of all Compact Semantic Credential revocation lists on the tenant.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_REVOCATION_LISTS_RETRIEVE_START
  • CREDENTIAL_COMPACT_SEMANTIC_REVOCATION_LISTS_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_REVOCATION_LISTS_RETRIEVE_FAIL
Authorizations:
bearerAuth

Responses

Request samples 

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

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve Compact Semantic Credential revocation list

Returns a Compact Semantic Credential revocation list by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_REVOCATION_RETRIEVE_START
  • CREDENTIAL_COMPACT_SEMANTIC_REVOCATION_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_REVOCATION_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
listId
required
string

The unique identifier of the revocation list you wish to retrieve.

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/revocation-lists/:listId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Update Compact Semantic Credential revocation status

Updates the credential status as revoked (invalid) or unrevoked (valid).

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_REVOCATION_SET_STATUS_START
  • CREDENTIAL_COMPACT_SEMANTIC_REVOCATION_SET_STATUS_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_REVOCATION_SET_STATUS_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Unique credential identifier (jti)

Request Body schema: application/json

Update revocation status

isRevoked
required
boolean

When set to true the credential will be revoked. When set to false, the credential will be unrevoked.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "isRevoked": true
}

Retrieve Compact Semantic Credential revocation status

Retrieve the revocation status of a Compact Semantic Credential by providing its ID.

Authorizations:
bearerAuth
path Parameters
id
required
string

Unique credential identifier (jti)

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/:id/revocation-status' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Compact Semantic Credentials PDF templates

Create a PDF template

Creates a Compact Semantic Credential PDF template based on a provided .zip file. Refer to our PDF template design tutorial for more information on how to design a template and structure the .zip file.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_CREATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/zip
string <binary>

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/pdf/templates' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/zip'

Response samples

Content type
application/json
{
  • "id": "4eea7654-d4c5-4eba-bd7a-5ca334d54725",
  • "name": "Certificate of participation",
  • "fileName": "certificate_of_participation",
  • "fonts": [
    ],
  • "metadata": {
    },
  • "fields": [
    ]
}

Retrieve all PDF templates

Retrieves a list of all Compact Semantic Credential PDF templates available on the tenant.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_RETRIEVE_LIST_START
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
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/v2/credentials/compact-semantic/pdf/templates?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "nextCursor": "0ecdcb57-ef2b-4aa1-be34-695c2d9d9486",
  • "data": [
    ]
}

Update a PDF template

Update an existing Compact Credential PDF template based on a provided .zip file. Refer to our PDF template design tutorial for more information on how to design a template and structure the .zip file.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_UPDATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_UPDATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

PDF Template ID

Request Body schema: application/zip
string <binary>

Responses

Request samples 

curl -i -X PUT \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/pdf/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/zip'

Response samples

Content type
application/json
{
  • "id": "4eea7654-d4c5-4eba-bd7a-5ca334d54725",
  • "name": "Certificate of participation",
  • "fileName": "certificate_of_participation",
  • "fonts": [
    ],
  • "metadata": {
    },
  • "fields": [
    ]
}

Retrieve a PDF template

Retrieves an existing Compact Semantic Credential PDF template using its ID.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_RETRIEVE_START
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

PDF Template ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/pdf/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "4eea7654-d4c5-4eba-bd7a-5ca334d54725",
  • "name": "Certificate of participation",
  • "fileName": "certificate_of_participation",
  • "fonts": [
    ],
  • "metadata": {
    },
  • "fields": [
    ]
}

Delete a PDF template

Delete an existing PDF template by providing its ID

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_DELETE_START
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_DELETE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_PDF_TEMPLATE_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

PDF Template ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/pdf/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Compact Semantic Credentials Apple Pass templates

Create an Apple Pass template

Creates an Apple Pass template based on the provided .zip file. Refer to our Design an Apple Pass template tutorial for more information on how to design the template and how to structure the .zip file.

The Apple Pass template uses the official Apple Pass bundle structure.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_CREATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
template
required
string <binary>

Includes your template files.

name
required
string [ 1 .. 1024 ] characters

Insert a name to identify this Apple digital pass template.

fileName
required
string [ 1 .. 100 ] characters

Insert the file name that will be assigned to Apple digital passes created from this template. Must only include alphanumeric characters, ''_'', or ''-'', and end with .pkpass.

teamIdentifier
required
string

The Team ID for the Apple Developer Program account that registered the pass type identifier.

passTypeIdentifier
required
string

The pass type identifier that’s registered with Apple. The value must be the same as the distribution certificate used to sign the pass.

wwdr
required
string

Apple G1 or G4 worldwide developer relations intermediate certificate.

signerCert
required
string

Apple pass signer certificate.

signerKey
required
string

The encrypted key of the Apple pass signer certificate.

signerKeyPassphrase
required
string

Passphrase for the encrypted key.

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/digitalpass/apple/templates' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F fileName=certificate_of_participation.pkpass \
  -F 'name=Certificate of participation' \
  -F passTypeIdentifier=pass.myproject.participation.pk \
  -F signerCert=string \
  -F signerKey=string \
  -F signerKeyPassphrase=string \
  -F teamIdentifier=GH5P43ABC \
  -F template=string \
  -F wwdr=string

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Retrieve all Apple Pass templates

Retrieves a list of all Apple Pass template available on the tenant.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_RETRIEVE_LIST_START
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
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/v2/credentials/compact-semantic/digitalpass/apple/templates?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Update an Apple Pass template

Updates an existing Apple Pass template by providing its ID and a .zip file. Refer to our Design an Apple Pass template tutorial for more information on how to design the template and how to structure the .zip file.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_UPDATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_UPDATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Apple Pass template ID

Request Body schema: multipart/form-data
template
required
string <binary>

Includes your template files.

name
required
string [ 1 .. 1024 ] characters

Insert a name to identify this Apple digital pass template.

fileName
required
string [ 1 .. 100 ] characters

Insert the file name that will be assigned to Apple digital passes created from this template. Must only include alphanumeric characters, ''_'', or ''-'', and end with .pkpass.

teamIdentifier
required
string

The Team ID for the Apple Developer Program account that registered the pass type identifier.

passTypeIdentifier
required
string

The pass type identifier that’s registered with Apple. The value must be the same as the distribution certificate used to sign the pass.

wwdr
required
string

Apple G1 or G4 worldwide developer relations intermediate certificate.

signerCert
required
string

Apple pass signer certificate.

signerKey
required
string

The encrypted key of the Apple pass signer certificate.

signerKeyPassphrase
required
string

Passphrase for the encrypted key.

Responses

Request samples 

curl -i -X PUT \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/digitalpass/apple/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F fileName=certificate_of_participation.pkpass \
  -F 'name=Certificate of participation' \
  -F passTypeIdentifier=pass.myproject.participation.pk \
  -F signerCert=string \
  -F signerKey=string \
  -F signerKeyPassphrase=string \
  -F teamIdentifier=GH5P43ABC \
  -F template=string \
  -F wwdr=string

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Retrieve an Apple Pass template

Retrieves an existing Apple Pass template by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_RETRIEVE_START
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Apple Pass template ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/digitalpass/apple/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Delete an Apple Pass template

Deletes an existing Apple Pass template by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_DELETE_START
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_DELETE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_APPLE_PASS_TEMPLATE_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Apple Pass template ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/digitalpass/apple/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Compact Semantic Credentials Google Pass templates

Create a Google Pass template

Creates a Google Pass template based on the provided .zip file. Refer to our Design a Google Pass template tutorial for more information on how to design the template and how to structure the .zip file.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_CREATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
template
required
string <binary>

Includes your template files.

name
required
string [ 1 .. 1024 ] characters

Insert a name to identify this Google Pass template.

issuerId
required
string

Google Wallet Pass signer issuer ID.

serviceAccountClientEmail
required
string

Email address of the Google Cloud Platform service account for accessing the Google Pay Passes API.

serviceAccountPrivateKey
required
string

Private key PEM of the Google Cloud Platform service account.

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/digitalpass/google/templates' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F issuerId=3388000000012346000 \
  -F 'name=Certificate of participation' \
  -F serviceAccountClientEmail=app-user@myproject.iam.gserviceaccount.com \
  -F serviceAccountPrivateKey=string \
  -F template=string

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Retrieve all Google Pass templates

Retrieves a list of all Google Pass templates available on your tenant.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_RETRIEVE_LIST_START
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
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/v2/credentials/compact-semantic/digitalpass/google/templates?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Update a Google Pass template

Updates a existing Google Pass template by providing its ID and a .zip file. Refer to our Design a Google Pass template tutorial for more information on how to design the template and how to structure the .zip file.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_UPDATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_UPDATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Google Pass template ID

Request Body schema: multipart/form-data
template
required
string <binary>

Includes your template files.

name
required
string [ 1 .. 1024 ] characters

Insert a name to identify this Google Pass template.

issuerId
required
string

Google Wallet Pass signer issuer ID.

serviceAccountClientEmail
required
string

Email address of the Google Cloud Platform service account for accessing the Google Pay Passes API.

serviceAccountPrivateKey
required
string

Private key PEM of the Google Cloud Platform service account.

Responses

Request samples 

curl -i -X PUT \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/digitalpass/google/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F issuerId=3388000000012346000 \
  -F 'name=Certificate of participation' \
  -F serviceAccountClientEmail=app-user@myproject.iam.gserviceaccount.com \
  -F serviceAccountPrivateKey=string \
  -F template=string

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Retrieve a Google Pass template

Retrieves an existing Google Pass template by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_RETRIEVE_START
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Google Pass template ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/digitalpass/google/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
  • "passType": "apple",
  • "name": "Certificate of participation",
  • "metadata": {
    }
}

Delete a Google Pass template

Delete a Google Pay Pass template by ID

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_DELETE_START
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_DELETE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_GOOGLE_PASS_TEMPLATE_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Google Pass template ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/compact-semantic/digitalpass/google/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Web Credentials

Sign a Web Semantic Credential

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

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_SIGN_START
  • CREDENTIAL_WEB_SEMANTIC_SIGN_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_SIGN_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

Web Semantic Credential payload to sign

required
object
proofType
string

This is an optional field which defines the cryptographic algorithm used to sign the credential. The credential Issuer's DID must contain a key that supports the corresponding signing capability. If no proofType is provided, the credential will be signed using the key that is available in the Issuer's DID:

  • If a Bls12381G2 key is available, the credential will be signed with a BbsSignature2022 proof. Credentials signed with this proof type support selective disclosure.
  • If a Bls12381G2 key is unavailable but a Ed25519 key is available, the credential will be signed with a Ed25519Signature2018 proof. Credentials signed with this proof type do not support selective disclosure.
  • If none of the two suitable keys are available, the request will be rejected and the credential will not be created.
Enum: "Ed25519Signature2018" "BbsSignature2022"
tag
string [ 1 .. 1024 ] characters

Insert a case sensitive tag to reference this credential. The gets stored as part of the credential metadata and can be used to search for it in the credential registry.

persist
boolean
Default: false

When set to true, both the credential and the credential metadata are stored in the credential registry. When set to false, only the following metadata is stored in the credential registry:

  • id
  • tag
  • credentialStatus
  • issuanceDate

    Credentials by nature tend to hold Personally Identifying Information (PII). Before storing credential data, familiarise yourself with compliance to any PII restrictions that may apply to your use-case.

revocable
boolean
Default: false

When set to true, the created credential can later be revoked. When set to false, the credential cannot be revoked. When set to true, https://w3id.org/vc-revocation-list-2020/v1 is injected into the credential @context object when it is issued. This references the JSON-LD definition of the credentialStatus object.

includeId
boolean
Default: false

When set to true, the signed credential identifier is included in both the credential object and the credential metadata. When set to false it is only included in the credential metadata.

Responses

Request samples

Content type
application/json
{
  • "payload": {
    },
  • "proofType": "Ed25519Signature2018",
  • "tag": "identifier123",
  • "persist": false,
  • "revocable": false,
  • "includeId": true
}

Response samples

Content type
application/json
{}

Retrieve all credential data

Returns all available data for existing credentials:

  • For credentials that were created with the persist flag set to true, the response contains both the credential and its metadata.
  • For credentials that were created with the persist flag set to false, the response only contains the metadata (id, tag, credentialStatus, issuanceDate).

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_RETRIEVE_LIST_START
  • CREDENTIAL_WEB_SEMANTIC_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
query Parameters
tag
string

Optional tag to filter on.

Example: tag=identifier123
type
string

Optional credential type to filter on.

Example: type=AlumniCredential
limit
number [ 1 .. 1000 ]

Range size of returned credential entries, default 100

Example: limit=2
cursor
string

Starting point for the range of credential entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/web-semantic?tag=identifier123&type=AlumniCredential&limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Retrieve credential data

Returns all available data for an existing credential that matches the provided ID:

  • For credentials that were created with the persist flag set to true, the response contains both the credential and its metadata.
  • For credentials that were created with the persist flag set to false, the response only contains the metadata (id, tag, credentialStatus, issuanceDate)

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_RETRIEVE_START
  • CREDENTIAL_WEB_SEMANTIC_RETRIEVE_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Credential ID

Responses

Request samples 

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

Response samples

Content type
application/json
Example
With persisted credential
With persisted credential
No persisted credential
{}

Delete credential data

Deletes all stored data for an existing credential that matches the provided ID. If the credential is revocable, it will also be permanently revoked.

Removed credential data cannot be recovered.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_DELETE_START
  • CREDENTIAL_WEB_SEMANTIC_DELETE_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Credential ID

Responses

Request samples 

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

Response samples

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

Verify a Web Semantic Credential

Verify a Web Semantic Credential by providing its payload. The credential is verified against the following criteria:

  • Issuer DID can be resolved, so that the referenced DID Document is available and valid and the public key is obtainable.
  • Proof is valid and the credential has not been tampered with.
  • JSON-LD context is valid for subject claims.

Optional verification checks:

  • If assertExpiry is set to true and the credential has a set expiration date, verification will fail if the expiration date has passed.
  • If checkRevocation is set to true and the provided credential contains a revocation status list, verification will fail if the credential has been set to revoked.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_VERIFY_START
  • CREDENTIAL_WEB_SEMANTIC_VERIFY_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_VERIFY_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json
required
object (VerifiableCredential)

Replace with the contents of the credential object from the response obtained when creating a Web Credential. Make sure you only include the contents of the credential object and not the entire response.

assertExpiry
boolean
Deprecated
Default: true

When set to true, verification will fail when expiration date has passed. This field is deprecated in favour of assertValidUntil, and will be disabled from September 2024.

checkRevocation
boolean
Default: true

When set to true, verification will fail when the credential has been revoked.

assertValidFrom
boolean
Default: true

When set to true, verification will fail when issuanceDate has not been reached.

assertValidUntil
boolean
Default: false

When set to true, verification will fail when expirationDate has passed. When specified, this overrides the deprecated assertExpiry property.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "verified": true,
  • "reason": {
    }
}

Web Credentials configuration

Create a Web Credential configuration

Creates a new Web Credential configuration, a specific set of rules and parameters that are used to create and validate a particular type of verifiable credential. These rules and parameters define how the credential is structured and what data it contains when issued.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_START
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The Credential Configuration payload

name
required
string [ 1 .. 1024 ] characters

Insert a meaningful name for the credential. This string is displayed on the top part of the credential in the holder's digital wallet. It is recommended to limit this value to 18 characters as any additional characters are not displayed on the credential.

description
string <= 1024 characters

Insert a meaningful description for the credential. This string is displayed below the name field on the credential in the holder's digital wallet. It is recommended to limist this value to 38 characters as any additional characters are not displayed on the credential.

type
required
string [ 1 .. 1024 ] characters

Used to differentiate between different Web credential configurations on your tenant. Thus, its value must:

  • Be unique across all Web credential configurations on your tenant.
  • Not be VerifiableCredential.
additionalTypes
Array of strings

Additional credential types that can be referenced. Each entry must be 1-1024 characters long, with no whitespaces allowed.

contexts
Array of strings

Additional JSON-LD contexts to be included in the credential. As part of the credential issuance MATTR VII will auto-inject the following contexts, which reference the W3C Verifiable Credential definitions:

required
object

Issuer details and branding for issued credentials. Refer to this video to learn more about branding best practices.

proofType
string

This is an optional field which defines the cryptographic algorithm used to sign the credential. The credential Issuer's DID must contain a key that supports the corresponding signing capability. If no proofType is provided, the credential will be signed using the key that is available in the Issuer's DID:

  • If a Bls12381G2 key is available, the credential will be signed with a BbsSignature2022 proof. Credentials signed with this proof type support selective disclosure.
  • If a Bls12381G2 key is unavailable and a Ed25519 key is available, the credential will be signed with a Ed25519Signature2018 proof. Credentials signed with this proof type do not support selective disclosure.
  • If none of the two suitable keys are available, the request will be rejected and the credential will not be created.
Enum: "Ed25519Signature2018" "BbsSignature2022"
object

Additional branding that will be applied to issued credentials. Refer to this video to learn more about branding best practices.

object

This is where you specify how to map claims (user attributes) into issued credentials. Each field in the object corresponds to a claim in the issued credential, and contains one or more from the following attributes:

  • mapFrom: References the path in the user object where the claim is available.
    • When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g. mapFrom: "claims['https://example.com/claim-name']").
    • mapForm is optional when defaultValue is provided, as the latter will be used for all issued credentials. This is referred to as a static claim.
  • defaultValue: Indicates what value is used if required is set to false (field is optional) and no value is provided by the claims source. When defaultValue is provided, mapFrom is optional.
  • required: Indicates whether the claim is required (default: false). When a required claim cannot be retrieved and no defaultValue is available, credential issuance will fail.
  • Example source context object*
    {
 "claims": {
   "given_name": "Jamie",
   "family_name": "Doe",
   "address": {
     "formatted": "116-118 Quay Street, Auckland CBD, Auckland 1010"
   }
 },
 "authenticationProvider": {
   "subjectId": "6d3aab7d-73af-5f61-b47c-109ef6f7558c",
   "url": "https://accounts.google.com"
 }
}
persist
boolean
Default: false

When set to true, both the issued credential and its metadata are stored in the credential registry. When set to false (default) only the following metadata is stored:

  • id
  • tag
  • credentialStatus
  • issuanceDate
revocable
boolean
Default: true

When set to true (default), the created credential can later be revoked. When set to false, the credential cannot be revoked. When set to true, https://w3id.org/vc-revocation-list-2020/v1 is injected into the credential @context object when it is issued. This references the JSON-LD definition of the credentialStatus object used to manage revocation status.

includeId
boolean
Default: false

When set to true, the signed credential identifier is included in both the credential object and the credential metadata. When set to false it is only included in the credential metadata.

claimSourceId
string <uuid>

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

object

Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds.

Responses

Request samples

Content type
application/json
{
  • "name": "Course credential",
  • "description": "This credential shows that the person has attended a course.",
  • "type": "CourseCredential",
  • "additionalTypes": [
    ],
  • "contexts": [],
  • "issuer": {},
  • "proofType": "Ed25519Signature2018",
  • "credentialBranding": {},
  • "claimMappings": {},
  • "persist": false,
  • "revocable": true,
  • "includeId": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "name": "Course credential",
  • "description": "This credential shows that the person has attended a course.",
  • "type": "CourseCredential",
  • "additionalTypes": [
    ],
  • "contexts": [],
  • "issuer": {},
  • "proofType": "Ed25519Signature2018",
  • "credentialBranding": {},
  • "claimMappings": {},
  • "persist": false,
  • "revocable": true,
  • "includeId": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Retrieve all Web Credential configurations

Returns a list of all Web Credential Configurations on your tenant.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_START
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned entries, default 100

Example: limit=2
cursor
string

Starting point for the range of entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
type
string

The optional credential type to filter on

Example: type=AlumniCredential

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v2/credentials/web-semantic/configurations?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h&type=AlumniCredential' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Retrieve a Web Credential configuration

Retrieve a Web Credential configuration by providing its ID.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_START
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Web Credential configuration unique identifier

Example: 3948c40e-6e19-4ffc-933c-91f643f24264

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v2/credentials/web-semantic/configurations/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "name": "Course credential",
  • "description": "This credential shows that the person has attended a course.",
  • "type": "CourseCredential",
  • "additionalTypes": [
    ],
  • "contexts": [],
  • "issuer": {},
  • "proofType": "Ed25519Signature2018",
  • "credentialBranding": {},
  • "claimMappings": {},
  • "persist": false,
  • "revocable": true,
  • "includeId": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Update a Web Credential configuration

Updates an existing Web Credential configuration by providing its ID.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_START
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Web Credential configuration unique identifier

Example: 3948c40e-6e19-4ffc-933c-91f643f24264
Request Body schema: application/json

Update a Credential Configuration

name
required
string [ 1 .. 1024 ] characters

Insert a meaningful name for the credential. This string is displayed on the top part of the credential in the holder's digital wallet. It is recommended to limit this value to 18 characters as any additional characters are not displayed on the credential.

description
string <= 1024 characters

Insert a meaningful description for the credential. This string is displayed below the name field on the credential in the holder's digital wallet. It is recommended to limist this value to 38 characters as any additional characters are not displayed on the credential.

type
required
string [ 1 .. 1024 ] characters

Used to differentiate between different Web credential configurations on your tenant. Thus, its value must:

  • Be unique across all Web credential configurations on your tenant.
  • Not be VerifiableCredential.
additionalTypes
Array of strings

Additional credential types that can be referenced. Each entry must be 1-1024 characters long, with no whitespaces allowed.

contexts
Array of strings

Additional JSON-LD contexts to be included in the credential. As part of the credential issuance MATTR VII will auto-inject the following contexts, which reference the W3C Verifiable Credential definitions:

required
object

Issuer details and branding for issued credentials. Refer to this video to learn more about branding best practices.

proofType
string

This is an optional field which defines the cryptographic algorithm used to sign the credential. The credential Issuer's DID must contain a key that supports the corresponding signing capability. If no proofType is provided, the credential will be signed using the key that is available in the Issuer's DID:

  • If a Bls12381G2 key is available, the credential will be signed with a BbsSignature2022 proof. Credentials signed with this proof type support selective disclosure.
  • If a Bls12381G2 key is unavailable and a Ed25519 key is available, the credential will be signed with a Ed25519Signature2018 proof. Credentials signed with this proof type do not support selective disclosure.
  • If none of the two suitable keys are available, the request will be rejected and the credential will not be created.
Enum: "Ed25519Signature2018" "BbsSignature2022"
object

Additional branding that will be applied to issued credentials. Refer to this video to learn more about branding best practices.

object

This is where you specify how to map claims (user attributes) into issued credentials. Each field in the object corresponds to a claim in the issued credential, and contains one or more from the following attributes:

  • mapFrom: References the path in the user object where the claim is available.
    • When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g. mapFrom: "claims['https://example.com/claim-name']").
    • mapForm is optional when defaultValue is provided, as the latter will be used for all issued credentials. This is referred to as a static claim.
  • defaultValue: Indicates what value is used if required is set to false (field is optional) and no value is provided by the claims source. When defaultValue is provided, mapFrom is optional.
  • required: Indicates whether the claim is required (default: false). When a required claim cannot be retrieved and no defaultValue is available, credential issuance will fail.
  • Example source context object*
    {
 "claims": {
   "given_name": "Jamie",
   "family_name": "Doe",
   "address": {
     "formatted": "116-118 Quay Street, Auckland CBD, Auckland 1010"
   }
 },
 "authenticationProvider": {
   "subjectId": "6d3aab7d-73af-5f61-b47c-109ef6f7558c",
   "url": "https://accounts.google.com"
 }
}
persist
boolean
Default: false

When set to true, both the issued credential and its metadata are stored in the credential registry. When set to false (default) only the following metadata is stored:

  • id
  • tag
  • credentialStatus
  • issuanceDate
revocable
boolean
Default: true

When set to true (default), the created credential can later be revoked. When set to false, the credential cannot be revoked. When set to true, https://w3id.org/vc-revocation-list-2020/v1 is injected into the credential @context object when it is issued. This references the JSON-LD definition of the credentialStatus object used to manage revocation status.

includeId
boolean
Default: false

When set to true, the signed credential identifier is included in both the credential object and the credential metadata. When set to false it is only included in the credential metadata.

claimSourceId
string <uuid>

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

object

Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds.

Responses

Request samples

Content type
application/json
{
  • "name": "Course credential",
  • "description": "This credential shows that the person has attended a course.",
  • "type": "CourseCredential",
  • "additionalTypes": [
    ],
  • "contexts": [],
  • "issuer": {},
  • "proofType": "Ed25519Signature2018",
  • "credentialBranding": {},
  • "claimMappings": {},
  • "persist": false,
  • "revocable": true,
  • "includeId": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "name": "Course credential",
  • "description": "This credential shows that the person has attended a course.",
  • "type": "CourseCredential",
  • "additionalTypes": [
    ],
  • "contexts": [],
  • "issuer": {},
  • "proofType": "Ed25519Signature2018",
  • "credentialBranding": {},
  • "claimMappings": {},
  • "persist": false,
  • "revocable": true,
  • "includeId": true,
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Delete a Web Credential configuration

Deletes an existing Web Credential configuration by providing its ID.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_START
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Web Credential configuration unique identifier

Example: 3948c40e-6e19-4ffc-933c-91f643f24264

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/core/v2/credentials/web-semantic/configurations/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Web Credentials revocation

Set credential revocation status

Sets the recovation status of the credential that matches the provided ID as true (revoked) or false (unrevoked).

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_REVOCATION_SET_STATUS_START
  • CREDENTIAL_WEB_SEMANTIC_REVOCATION_SET_STATUS_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_REVOCATION_SET_STATUS_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Credential ID

Example: a80a5e7e-1972-4be6-8a4e-2adf09badf24
Request Body schema: application/json

Setting the revocation status

isRevoked
required
boolean

Indicates whether the credential is revoked (true) or not (false).

Responses

Request samples

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

Response samples

Content type
application/json
Example
Credential not revocable
Credential not revocable
Credential does not exist
Revocation list is not found
{
  • "code": "NotFound",
  • "message": "Validation Error",
  • "details": [
    ]
}

Retrieve credential revocation status

Returns the revocation status of the credential matching the provided ID.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_REVOCATION_RETRIEVE_START
  • CREDENTIAL_WEB_SEMANTIC_REVOCATION_RETRIEVE_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_REVOCATION_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Credential ID

Example: a80a5e7e-1972-4be6-8a4e-2adf09badf24

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/web-semantic/:id/revocation-status' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "isRevoked": false
}

Retrieve revocation list

Returns the revocation list matching the provided ID.

path Parameters
id
required
string <uuid>

Revocation list ID. This value can be found within the credential you created. Look at the value for Credentential.credential.credentialStatus.id, the string after https://tenant.vii.mattr.global/core/v1/revocation-lists/ is what you're looking for

Example: cc641396-3750-43c8-b8b8-f30d74eb3fb3

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/revocation-lists/:id'

Response samples

Content type
application/json
{}

Create a revocation message payload

Returns a message in JWM format that can be used to notify subjects based on their credential revocation status change.

To send a notification to the Subject DID holder, use the returned payload with the encrypt and send endpoints.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_REVOCATION_MESSAGE_PAYLOAD_CREATE_START
  • CREDENTIAL_WEB_SEMANTIC_REVOCATION_MESSAGE_PAYLOAD_CREATE_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_REVOCATION_MESSAGE_PAYLOAD_CREATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Unique identifier for the credential whose status has changed.

Example: 873277c0-a162-11ea-8a1d-a111119347e6
Request Body schema: application/json

Create a JWM message payload

from
required
string non-empty

The sender's DID URL, obtained from the id field of the first keyAgreement entry of the DID document. This must be a DID with a key type suitable for messaging (not a BLS key type).

to
required
Array of strings

The intended recipients DID URL.

Responses

Request samples

Content type
application/json
{
  • "from": "did:web:organization.com",
  • "to": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "string",
  • "to": [
    ],
  • "from": "did:web:organization.com",
  • "created_time": 0,
  • "body": {
    }
}

Web Credentials presentations

Create a presentation template

Creates a presentation template defining what type of credential is required for a particular verification workflow. Presentation templates are used to create presentation requests that are shared with a specific holder.

Analytic events

  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_CREATE_START
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_CREATE_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The template

domain
required
string

Informs the wallet holder what domain is the verification request coming from. The value must match your tenant URL or your custom domain (if you have one set up). If the domain validation is unsuccessful, the wallet will not let the user proceed with the verification workflow.

If you set up a custom domain later, any previous templates created where the domain is your tenant URL will become invalid. You will need to change any prior templates to use the custom domain.

name
required
string

Unique value that is used internally to manage your templates. It must be unique across all presentation templates on your tenant, but is not shown to the holder.

required
Array of CreatePresentationQueryByExample (object) or CreatePresentationQueryByFrame (object) or CreatePresentationDidAuthTemplate (object)

Indicates what type of query method would be used by presentation requests created from this presentation template:

  • QueryByExample: This query method uses the credential type and trustedIssuer to only accept verifiable presentations that match these parameters.
  • QueryByFrame: This query method is used to create presentation requests that wonly require specific claims in the verifiable presentations and thus enable selective disclosure.
  • DidAuth: This query method id used to authenticate with the tenant and provide the holder's DID. You can request multiple credentials in one request by adding additioanl credentialQuery objects to the query array.

Responses

Request samples

Content type
application/json
Example
Query by Example
Query by Example
Query by Frame
DID Auth
{
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}

Retrieve all presentation templates

Returns a list of all presentation templates on your tenant.

Analytic events

  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_LIST_START
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_LIST_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
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/v2/credentials/web-semantic/presentations/templates?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Retrieve a presentation template

Retrieve an existing presentation template by its ID.

Analytic events

  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_START
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Presentation template ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/web-semantic/presentations/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "64e45290-9980-11ea-b872-f1bee5fb328f",
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}

Delete a presentation template

Deletes an existing presentation template by its ID.

Analytic events

  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_DELETE_START
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_DELETE_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Presentation template ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/v2/credentials/web-semantic/presentations/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Update a presentation template

Updates an existing presentation template by its ID.

Analytic events

  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_UPDATE_START
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_UPDATE_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Presentation template ID

Request Body schema: application/json
id
string
domain
required
string

Informs the wallet holder what domain is the verification request coming from. The value must match your tenant URL or your custom domain (if you have one set up). If the domain validation is unsuccessful, the wallet will not let the user proceed with the verification workflow.

If you set up a custom domain later, any previous templates created where the domain is your tenant URL will become invalid. You will need to change any prior templates to use the custom domain.

name
required
string

Unique value that is used internally to manage your templates. It must be unique across all presentation templates on your tenant, but is not shown to the holder.

required
Array of CreatePresentationQueryByExample (object) or CreatePresentationQueryByFrame (object) or CreatePresentationDidAuthTemplate (object)

Indicates what type of query method would be used by presentation requests created from this presentation template:

  • QueryByExample: This query method uses the credential type and trustedIssuer to only accept verifiable presentations that match these parameters.
  • QueryByFrame: This query method is used to create presentation requests that wonly require specific claims in the verifiable presentations and thus enable selective disclosure.
  • DidAuth: This query method id used to authenticate with the tenant and provide the holder's DID. You can request multiple credentials in one request by adding additioanl credentialQuery objects to the query array.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "domain": "string",
  • "name": "string",
  • "query": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "64e45290-9980-11ea-b872-f1bee5fb328f",
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}

Create a presentation request

Creates a short lived presentation request based on an existing presentation template. The request is returned in the form of a JWM message and must be signed and sent to the holder via one of the following methods:

  • QR code.
  • Deeplink.
  • Encrypted and sent as a wallet notification.

Analytic events

  • PRESENTATION_WEB_SEMANTIC_REQUEST_CREATE_START
  • PRESENTATION_WEB_SEMANTIC_REQUEST_CREATE_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_REQUEST_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The presentation request payload

challenge
required
string

Unique transaction identifier. While you can use it as a transaction id element, consider that the challenge is part of the signed presentation request and it is not encrypted. Therefore, it should not be considered secure.

did
required
string

This is the DID associated with the verifier. It must be available on the tenant and have a key type that is able to be used for messaging (e.g. a ed25519 key type).

templateId
required
string

The id value of an existing presentation template that will be used to create the presentation request.

expiresTime
number

Once the time (Unix time) is reached the presentation corresponding to the challenge will not be accepted. For the purpose of testing you may wish to extend this out. Value cannot be more than 30 minutes (1800000ms) in the future, which is the maximal expiry period for a presentation request. Defaults to five minutes if no value is provided.

callbackUrl
required
string <uri>

This is the path that you want MATTR VII to message (in the form of a JSON body) once it has received and processed the verifiable presentation from the mobile wallet holder:

  • Must be a valid URL.
  • Must use the HTTPS protocol.
  • Must not be an IP address.
  • Must not include query parameters.
  • Must be available, accept POST requests and respond with a 200 OK.

    The callback URL is not present directly in the signed presentation request JWS. We recommend including a secret unique identifier in the URL to create a unique secured callback URL for each request which would make it hard to guess. We recommend for the callback endpoint to always respond with a 404 header to any unsuccessful calls.

Responses

Request samples

Content type
application/json
{
  • "challenge": "64e45290-9980-11ea-b872-f1bee5fb328f",
  • "did": "did:key:z6Mkt7bFYc4V2HdAxwhMtaY6cgJckYXwhYdPLJCcnVqzrkpr",
  • "templateId": "64e45290-9980-11ea-b872-f1bee5fb328f",
  • "expiresTime": 1592955632103,
  • "callbackUrl": "https://your-website.com/api/callback"
}

Response samples

Content type
application/json
{}

Verify a verifiable presentation

Verifies a provided verifiable presentation that adheres to the W3C Verifiable Credential Data Model:

  • Ensures the presentation conforms to the VC Data model.
  • For each verifiableCredential objects:
    • Issuer DID can be resolved.
    • JSON-LD context is valid for subject claims.
    • Proof is valid & the credential has not been tampered with.
    • Is not in a revoked status on a RevocationList2020.
    • The proof is valid for each subjectDID to prove ownership.
    • Valid proof exists for the presentation holderDID.

The request must include a presentation object that adheres to the W3C Verifiable Credential Data Model.

If a challenge and/or domain is provided they are used for credential verification. Otherwise, the challenge and/or domain within the presentation proof is used instead.

Analytic events

  • PRESENTATION_WEB_SEMANTIC_VERIFY_START
  • PRESENTATION_WEB_SEMANTIC_VERIFY_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_VERIFY_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

Presentation to verify

required
object
challenge
string
domain
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
Example
Verified
Verified
Invalid
{
  • "verified": true
}

Linked Data

Convert linked-data documents

Compressed Web credentials are currently marked as 'Retired' as per our Service Level Agreement. This capability is no longer actively enhanced or supported and will be removed from the MATTR VII platform on 19 Aug 2024. It is highly recommended to issue Compact Semantic Credentials instead. Convert a document like a JSON-LD Credential or a Verifiable Presentation into a CBOR-LD document, and vice versa.

The Convert operation can accept JSON-LD documents as an input and convert them to a CBOR-LD document represented in Base64. CBOR-LD documents can represent the same information in a smaller size that is more friendly for offline use-cases, such as embedding into a QR code printed onto physical media or a PDF.

Documents can also be converted from CBOR-LD in Base64 format to JSON-LD, the response can either be encoded in Base 64 or plain JSON. This is useful for accepting compressed Credentials or Verifiable Presentations and converting them for use on other operations like Verify a Credential or Verify a Presentation.

Wallet Presentations
The MATTR mobile wallet can create verifiable presentations from a single credential in a CBOR-LD format and encode this into a QR, a further layer of GZip compression is performed.

Limitations
Calculating the exact size of a credential/document that can be encoded into a QR and safely read by a camera is not straightforward. Larger credentials are unlikely to work, including those with embedded images (photos), large nested claims, or credentials with large signatures like BBS, it is generally best to confirm by testing across a range of devices.

Deeply nested JSON-LD structures are currently unable to be converted to CBOR-LD due to limitations of the library, so it is possible to see errors.

We are aware that inline contexts may affect the performance for CBOR-LD compression. The Create Credential endpoint uses an inline @vocab context, this may change in the future.

Analytic events

  • LINKED_DATA_CONVERT_STARTLINKED_DATA_CONVERT_START
  • LINKED_DATA_CONVERT_STARTLINKED_DATA_CONVERT_SUCCESS
  • LINKED_DATA_CONVERT_STARTLINKED_DATA_CONVERT_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The request document data and options

required
object
required
string or object

Responses

Request samples

Content type
application/json
Example
Convert a JSON-LD document to CBOR-LD
Convert a JSON-LD document to CBOR-LD
Convert a CBOR-LD document to JSON-LD
{
  • "options": {
    },
  • "data": {}
}

Response samples

Content type
application/json
Example
CBOR-LD document output
CBOR-LD document output
JSON-LD document output
{
  • "metadata": {
    },
  • "data": "2QUBpgBzaHR0cHM6Ly9zY2hlbWEub3JnLwIZBz4ZEJppUHJvZmVzc29yGRGSaEphbmUgRG9lGRUobig0MjUpIDEyMy00NTY3GRWsggFvd3d3LmphbmVkb2UuY29t"
}

Mobile Credentials

Sign a Mobile Credential

Signs the provided Mobile Credential payload using the referenced Document Signer Certificate (DSC).

Analytic events

  • MOBILE_CREDENTIAL_SIGN_START
  • MOBILE_CREDENTIAL_SIGN_SUCCESS
  • MOBILE_CREDENTIAL_SIGN_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json
required
object (SignRequestPayload)
documentSignerId
string <uuid>

Identifier of the DSC that will be used to sign the Mobile Credential.

Responses

Request samples

Content type
application/json
{
  • "payload": {
    },
  • "documentSignerId": "d1bd2bfe-76e0-46bd-a958-78eaa909132a"
}

Response samples

Content type
application/json
{
  • "encoded": "string",
  • "decoded": {
    }
}

Delete Mobile Credential metadata

Deletes all stored data for an existing Mobile Credential that matches the provided ID.

Removed credential data cannot be recovered.

Analytic events

  • USER_CREDENTIAL_DELETE_START
  • USER_CREDENTIAL_DELETE_SUCCESS
  • USER_CREDENTIAL_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string

Mobile Credential ID

Responses

Request samples 

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

Response samples

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

Mobile Credential Configuration

Create a Mobile Credential configuration

Creates a new Mobile Credential configuration, a specific set of rules and parameters that are used to create and validate a particular type of verifiable credential. These rules and parameters define how the credential is structured and what data it contains when issued.

Analytic events

  • MOBILE_CREDENTIAL_CONFIGURATION_CREATE_START
  • MOBILE_CREDENTIAL_CONFIGURATION_CREATE_SUCCESS
  • MOBILE_CREDENTIAL_CONFIGURATION_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The Mobile Credential configuration payload

type
required
string [ 1 .. 1024 ] characters

Used to differentiate between different Mobile credential configurations on your tenant. Thus, its value must:

  • Be unique across all Mobile credential configurations on your tenant.
  • Not be VerifiableCredential.
required
object (ClaimMappings)

This is where you specify how to map claims (user attributes) into issued credentials.

claimSourceId
string <uuid>

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

required
object

Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds. Note that credential issuance will fail if the credential expiry date is later than that of the Document Signer Certificate (DSC) used to sign it.

object

Used to apply branding to issued credentials.

Responses

Request samples

Content type
application/json
{
  • "type": "DriverLicence",
  • "claimMappings": {
    },
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    },
  • "branding": {
    }
}

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "branding": {
    },
  • "type": "DriverLicence",
  • "claimMappings": {
    },
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Retrieve all Mobile Credential configurations

Retrieves all Mobile Credential Configurations from your tenant.

Analytic events

  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_START
  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_SUCCESS
  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
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
type
string

Optional credential type to filter on

Example: type=AlumniCredential

Responses

Request samples 

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

Response samples

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

Retrieve a Mobile Credential configuration

Retrieves an existing Mobile Credential Configuration by providing its ID.

Analytic events

  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_START
  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_SUCCESS
  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Mobile Credential Configuration ID

Example: 3948c40e-6e19-4ffc-933c-91f643f24264

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "branding": {
    },
  • "type": "DriverLicence",
  • "claimMappings": {
    },
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Update a Mobile Credential configuration

Updates an existing Mobile Credential configuration by providing its ID.

Analytic events

  • MOBILE_CREDENTIAL_CONFIGURATION_UPDATE_START
  • MOBILE_CREDENTIAL_CONFIGURATION_UPDATE_SUCCESS
  • MOBILE_CREDENTIAL_CONFIGURATION_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Mobile Credential Configuration ID

Example: 3948c40e-6e19-4ffc-933c-91f643f24264
Request Body schema: application/json

Update a Mobile Credential configuration

type
required
string [ 1 .. 1024 ] characters

Used to differentiate between different Mobile credential configurations on your tenant. Thus, its value must:

  • Be unique across all Mobile credential configurations on your tenant.
  • Not be VerifiableCredential.
required
object (ClaimMappings)

This is where you specify how to map claims (user attributes) into issued credentials.

claimSourceId
string <uuid>

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

required
object

Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds. Note that credential issuance will fail if the credential expiry date is later than that of the Document Signer Certificate (DSC) used to sign it.

object

Used to apply branding to issued credentials.

Responses

Request samples

Content type
application/json
{
  • "type": "DriverLicence",
  • "claimMappings": {
    },
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    },
  • "branding": {
    }
}

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "branding": {
    },
  • "type": "DriverLicence",
  • "claimMappings": {
    },
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    }
}

Delete a Mobile Credential configuration

Deletes an existing Mobile Credential configuration by providing its ID.

Analytic events

  • MOBILE_CREDENTIAL_CONFIGURATION_DELETE_START
  • MOBILE_CREDENTIAL_CONFIGURATION_DELETE_SUCCESS
  • MOBILE_CREDENTIAL_CONFIGURATION_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Mobile Credential Configuration ID

Example: 3948c40e-6e19-4ffc-933c-91f643f24264

Responses

Request samples 

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

Response samples

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

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:
bearerAuth
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:
bearerAuth

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:
bearerAuth
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": [
    ]
}

DSC

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:
bearerAuth
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:
bearerAuth

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:
bearerAuth
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:
bearerAuth
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:
bearerAuth
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>'

Authentication Provider

Configure an Authentication Provider

Configures an Authentication Provider on the tenant.

An authentication or identity provider (IdP) is a platform that is typically used to store and manage user accounts on behalf of an organisation or a service provider. MATTR VII uses the authentication provider to authenticate end users before issuing them credentials.

Only one authentication provider can be configured on a tenant.

The /.well-known/openid-configuration endpoint of the Authentication Provider must contain values for the authorization_endpoint, token_endpoint and scopes_supported.

Analytic events

  • USER_AUTHENTICATION_PROVIDER_CREATE_START
  • USER_AUTHENTICATION_PROVIDER_CREATE_SUCCESS
  • USER_AUTHENTICATION_PROVIDER_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The Authentication Provider payload

url
string <uri>

Base url for your Authentication Provider well-known endpoint:

  • Must be a valid URL.
  • Must use the HTTPS protocol.
  • Must not be an IP address.
  • Must not contain query parameters. Port and fragment parameters will be dropped.
  • URL must use https and have a valid public TLD.
  • Unicode will be converted to ASCII.
scope
Array of strings
Default: ["openid","profile","email"]

OpenID scopes to use during authentication. Each scope returns a set of user attributes which are called claims. Be sure to test that right scopes are added to get all the information you need.

clientId
required
string

The client ID of the application client created on your IdP.

clientSecret
required
string

The client secret of the application client created on your IdP.

tokenEndpointAuthMethod
string
Default: "client_secret_basic"

Authentication method for your IdP token endpoint:

  • client_secret_post: Your credentials are passed as parameters in the request body.
  • client_secret_basic (default): Your credentials are passed as a base 64 encoded token.
Enum: "client_secret_basic" "client_secret_post"
object

Additional parameters (maximum 1000 entries allowed) that will be included in the request to your IdP. These parameters are identical for every request as defined in your configuration. An example would be setting the prompt to be login to let your IdP know it should show the login page every time. Keys must be strings. Values of top-level object keys must stringify to less than 1000 characters.

forwardedRequestParameters
Array of strings

In contrast to staticRequestParameters, you can provide dynamic parameters that are fetched uniquely for each request to make the user journey more seamless. You can forward params to your IdP like login_hint which will pass the email of the user starting the flow. Values are limited to 1000 characters each, and cannot override any core Authorize Parameters.

claimsToPersist
Array of strings
Default: []

List of claims to persist from your IdP to MATTR VII. If you have attributes from the ID token (e.g. email, picture, etc.) that you would like persisted on MATTR VII, add them to this array. By default this array is empty, meaning no claims are persisted on MATTR VII.

Responses

Request samples

Content type
application/json
{
  • "url": "https://example-university.au.auth0.com",
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "QNwfa4Yi4Im9zy1u_15n7SzWKt-9G5cdH0r1bONRpUPfN-UIRaaXv_90z8V6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": "login_hint",
  • "claimsToPersist": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "redirectUrl": "https://tenant.vii.mattr.global/core/v1/oauth/authentication/callback",
  • "url": "http://example.com",
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "***********************************************************6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": "login_hint",
  • "claimsToPersist": [
    ]
}

Retrieve all Authentication Providers

Returns a list of all Authentication Providers on your tenant.

Analytic events

  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_START
  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_SUCCESS
  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned entries, default 100

Example: limit=2
cursor
string

Starting point for the range of entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples 

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

Response samples

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

Retrieve an Authentication Provider

Retrieve an existing Authentication Provider by providing its ID.

Analytic events

  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_START
  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_SUCCESS
  • USER_AUTHENTICATION_PROVIDER_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Authentication Provider ID

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

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "redirectUrl": "https://tenant.vii.mattr.global/core/v1/oauth/authentication/callback",
  • "url": "http://example.com",
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "***********************************************************6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": "login_hint",
  • "claimsToPersist": [
    ]
}

Update an Authentication Provider

Updates an existing Authentication Provider by providing its ID.

Analytic events

  • USER_AUTHENTICATION_PROVIDER_UPDATE_START
  • USER_AUTHENTICATION_PROVIDER_UPDATE_SUCCESS
  • USER_AUTHENTICATION_PROVIDER_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Authentication Provider ID

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

Update an Authentication Provider

scope
Array of strings
Default: ["openid","profile","email"]

OpenID scopes to use during authentication. Each scope returns a set of user attributes which are called claims. Be sure to test that right scopes are added to get all the information you need.

clientId
required
string

The client ID of the application client created on your IdP.

clientSecret
string

The client secret of the application client created on your IdP.

tokenEndpointAuthMethod
string
Default: "client_secret_basic"

Authentication method for your IdP token endpoint:

  • client_secret_post: Your credentials are passed as parameters in the request body.
  • client_secret_basic (default): Your credentials are passed as a base 64 encoded token.
Enum: "client_secret_basic" "client_secret_post"
object

Additional parameters (maximum 1000 entries allowed) that will be included in the request to your IdP. These parameters are identical for every request as defined in your configuration. An example would be setting the prompt to be login to let your IdP know it should show the login page every time. Keys must be strings. Values of top-level object keys must stringify to less than 1000 characters.

forwardedRequestParameters
Array of strings

In contrast to staticRequestParameters, you can provide dynamic parameters that are fetched uniquely for each request to make the user journey more seamless. You can forward params to your IdP like login_hint which will pass the email of the user starting the flow. Values are limited to 1000 characters each, and cannot override any core Authorize Parameters.

claimsToPersist
Array of strings
Default: []

List of claims to persist from your IdP to MATTR VII. If you have attributes from the ID token (e.g. email, picture, etc.) that you would like persisted on MATTR VII, add them to this array. By default this array is empty, meaning no claims are persisted on MATTR VII.

Responses

Request samples

Content type
application/json
{
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "QNwfa4Yi4Im9zy1u_15n7SzWKt-9G5cdH0r1bONRpUPfN-UIRaaXv_90z8V6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": "login_hint",
  • "claimsToPersist": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "redirectUrl": "https://tenant.vii.mattr.global/core/v1/oauth/authentication/callback",
  • "url": "http://example.com",
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "***********************************************************6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": "login_hint",
  • "claimsToPersist": [
    ]
}

Delete an Authentication Provider

Deletes an existing Authentication Provider by providing its ID.

Analytic events

  • USER_AUTHENTICATION_PROVIDER_DELETE_START
  • USER_AUTHENTICATION_PROVIDER_DELETE_SUCCESS
  • USER_AUTHENTICATION_PROVIDER_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Authentication Provider ID

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

Responses

Request samples 

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

Response samples

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

Interaction Hook

Configure Interaction Hook

Configure the Interaction Hook for the OpenID4VCI protocol on your tenant. Many credential issuance journeys require the issuer to perform custom interactions with the user. This could be gathering more information, performing additional authentication steps (E.g, 2FA, MFA or biometric checks) or communicating the terms of service. To facilitate this requirement, you can configure MATTR VII to invoke an interaction hook which will redirect the user to a custom component during the credential issuance journey. This redirect happens after the user is authenticated with your configured identity provider but before the credential is issued to the user. Upon successful completion of the interaction hook, your custom component will redirect the user back to their digital wallet to complete the credential issuance flow. Your interaction hook component can be either a web or native application.  We recommend using a web interface because it's more compatible with most scenarios.

You can only configure one interaction hook on your MATTR VII tenant. If you require several custom interactions as part of the credential issuance workflow, they should all be linked into a single interaction hook component.

Analytic events

  • CREDENTIAL_PROVIDER_OPENID_CONFIGURATION_UPDATE_START
  • CREDENTIAL_PROVIDER_OPENID_CONFIGURATION_UPDATE_SUCCESS
  • CREDENTIAL_PROVIDER_OPENID_CONFIGURATION_UPDATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The Interaction Hook configuration payload

object (OpenIdConfigurationInteractionHookRequest)

Interaction Hook configuration.

Responses

Request samples

Content type
application/json
{}

Response samples

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

Retrieve Interaction Hook

Retrieves the Interaction Hook configuration from your tenant.

Analytic events

  • CREDENTIAL_PROVIDER_OPENID_CONFIGURATION_RETRIEVE_START
  • CREDENTIAL_PROVIDER_OPENID_CONFIGURATION_RETRIEVE_SUCCESS
  • CREDENTIAL_PROVIDER_OPENID_CONFIGURATION_RETRIEVE_FAIL
Authorizations:
bearerAuth

Responses

Request samples 

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

Response samples

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

Claims Source

Configure a claims source

Configures a new claims source for your tenant. When issuing a new credential, MATTR VII will make either a GET or a POST request to the claims source using the configured request parameters and fetch available data. This fetched data can then be included in the issued credential.

Analytic event

  • CLAIM_SOURCE_CREATE_START
  • CLAIM_SOURCE_CREATE_SUCCESS
  • CLAIM_SOURCE_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The claim source payload

name
required
string

Claims source name.

url
required
string

Claims source URL:

  • Must be a valid URL.
  • Must use the HTTPS protocol.
  • Must not be an IP address.
  • Must not include query parameters.
  • Unicode will be converted to ASCII.
requestMethod
string

Indicates the request method MATTR VII will use when retrieving data from this claims source. Both the GET and POST method are supported. If no value is provided, GET is used by default. When using POST, all requestParameters must be included in the request body in JSON format.

Enum: "GET" "POST"
required
Mapping only (object) or Mapping with fallback (object) or Static value (object)

Use this object to define how to map request parameters that are sent to your claims source using the mapFrom and defaultValue properties:

  • When only providing mapFrom, the request parameter will be mapped from the defined path. If mapping fails, no alternative value is used. You can map data from both the claims and credentialConfiguration objects.
  • When providing both mapFrom and defaultValue, MATTR VII will attempt to map the request parameter from the defined path. If mapping fails, the defaultValue is used instead.
  • When only providing defaultValue, its value is used to populate the request parameter, regardless of any available claims values.
required
API Key (object) or OAuth Client Credentials (object)

Authentication method configuration to access the claims source.

Responses

Request samples

Content type
application/json
Example
Authorization with x-api-key header
Authorization with x-api-key header
Authorization with OAuth 2.0 client credentials
{
  • "name": "Claims source accepting a x-api-key header",
  • "url": "https://example.com/api/data",
  • "authorization": {
    },
  • "requestParameters": {
    }
}

Response samples

Content type
application/json
Example
Authorization with x-api-key header
Authorization with x-api-key header
Authorization with OAuth 2.0 client credentials
{
  • "name": "Claims source accepting a x-api-key header",
  • "url": "https://example.com/api/data",
  • "authorization": {
    },
  • "requestParameters": {
    }
}

Retrieve all claims sources

Returns a list of all claims sources configured on your tenant.

Analytic event

  • CLAIM_SOURCE_RETRIEVE_LIST_START
  • CLAIM_SOURCE_RETRIEVE_LIST_SUCCESS
  • CLAIM_SOURCE_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned entries, default 100

Example: limit=2
cursor
string

Starting point for the range of entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples 

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

Response samples

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

Retrieve a claims source

Retrieves an existing claims source by providing its claimSourceID.

Analytic event

  • CLAIM_SOURCE_RETRIEVE_START
  • CLAIM_SOURCE_RETRIEVE_SUCCESS
  • CLAIM_SOURCE_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Claims source ID

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

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "57fa09e2-82f3-4d3d-9eca-d0253e84a4e6",
  • "name": "My claims from example.com",
  • "url": "https://example.com",
  • "requestMethod": "GET",
  • "requestParameters": {
    },
  • "authorization": {
    }
}

Update a claims source

Updates an existing claim source by providing its claimSourceID.

Analytic event

  • CLAIM_SOURCE_UPDATE_START
  • CLAIM_SOURCE_UPDATE_SUCCESS
  • CLAIM_SOURCE_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Claims source ID

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

The updated claims source payload

name
required
string

Claims source name.

url
required
string

Claims source URL:

  • Must be a valid URL.
  • Must use the HTTPS protocol.
  • Must not be an IP address.
  • Must not include query parameters.
  • Unicode will be converted to ASCII.
requestMethod
string

Indicates the request method MATTR VII will use when retrieving data from this claims source. Both the GET and POST method are supported. If no value is provided, GET is used by default. When using POST, all requestParameters must be included in the request body in JSON format.

Enum: "GET" "POST"
required
Mapping only (object) or Mapping with fallback (object) or Static value (object)

Use this object to define how to map request parameters that are sent to your claims source using the mapFrom and defaultValue properties:

  • When only providing mapFrom, the request parameter will be mapped from the defined path. If mapping fails, no alternative value is used. You can map data from both the claims and credentialConfiguration objects.
  • When providing both mapFrom and defaultValue, MATTR VII will attempt to map the request parameter from the defined path. If mapping fails, the defaultValue is used instead.
  • When only providing defaultValue, its value is used to populate the request parameter, regardless of any available claims values.
required
API Key (object) or OAuth Client Credentials (object)

Authentication method configuration to access the claims source.

Responses

Request samples

Content type
application/json
{
  • "name": "My claims from example.com",
  • "url": "https://example.com",
  • "requestMethod": "GET",
  • "requestParameters": {
    },
  • "authorization": {
    }
}

Response samples

Content type
application/json
{
  • "id": "57fa09e2-82f3-4d3d-9eca-d0253e84a4e6",
  • "name": "My claims from example.com",
  • "url": "https://example.com",
  • "requestMethod": "GET",
  • "requestParameters": {
    },
  • "authorization": {
    }
}

Delete a claims source

Deletes an existing claims source by providing its claimSourceID.

Analytic event

  • CLAIM_SOURCE_DELETE_START
  • CLAIM_SOURCE_DELETE_SUCCESS
  • CLAIM_SOURCE_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Claims source ID

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

Responses

Request samples 

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

Response samples

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

Credential Issuance

Request authorization for access to resources

This endpoint is used to request authorization from the user for access to the requested resources. After the user approves the request, an authorization code is returned to the client. See https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-authorization-endpoint See https://www.rfc-editor.org/rfc/rfc6749.html#section-3.1

Analytic events

  • OPEN_ID_AUTHORIZE_START
  • OPEN_ID_AUTHORIZE_SUCCESS
  • OPEN_ID_AUTHORIZE_FAIL
query Parameters
response_type
required
string

The response type, which must be 'code'.

Value: "code"
client_id
required
string

The client identifier.

redirect_uri
required
string

The URI to which the authorization server will redirect the user-agent with the authorization code.

scope
required
string

The scope of the access request.

state
string

An opaque value used by the client to maintain state between the request and callback.

code_challenge_method
required
string

The method used to derive the code_challenge, which must be 'S256'.

Value: "S256"
code_challenge
required
string

A high entropy random challenge generated by the client.

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/oauth/authorize?response_type=code&client_id=string&redirect_uri=string&scope=string&state=string&code_challenge_method=S256&code_challenge=string'

Exchange authorization code for access token

This endpoint is used to exchange an authorization code for an access token. The authorization code is obtained from the authorization endpoint after the user has authenticated and granted access. See https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-token-endpoint

Analytic events

  • OPEN_ID_TOKEN_START
  • OPEN_ID_TOKEN_SUCCESS
  • OPEN_ID_TOKEN_FAIL
Request Body schema: application/x-www-form-urlencoded
client_id
required
string

The client identifier.

grant_type
required
string

The grant type, which must be 'authorization_code'.

Value: "authorization_code"
redirect_uri
required
string

The redirect URI that was used in the authorization request.

code
required
string

The authorization code obtained from the authorization endpoint.

code_verifier
required
string

SHA256 hash of the code_challenge in the authorization request.

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.vii.{region}.mattr.global/core/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d client_id=string \
  -d code=string \
  -d code_verifier=string \
  -d grant_type=authorization_code \
  -d redirect_uri=string

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "scope": "string"
}

Issue a verifiable credential

Issues a verifiable credential to a subject as part of the OpenID4VCI protocol.

See https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-endpoint

Analytic events

  • OPEN_ID_CREDENTIAL_START
  • OPEN_ID_CREDENTIAL_SUCCESS
  • OPEN_ID_CREDENTIAL_FAIL
Authorizations:
bearerAuthOpenIdCredentials
Request Body schema: application/json
One of
format
required
string

Credential format, always ldp_vc for Web Semantic Credentials.

Value: "ldp_vc"
required
object
object

JSON object containing proof of possession of the key material the issued Credential shall be bound to.

Responses

Request samples

Content type
application/json
Example
Request to issue a Web Semantic Credential
Request to issue a Web Semantic Credential
Request to issue a Compact Semantic Credential
Request to issue a Compact Credential
Request to issue a Mobile Credential
{
  • "format": "ldp_vc",
  • "credential_definition": {},
  • "proof": {
    }
}

Response samples

Content type
application/json
{}

Create an OpenID4VCI credential offer

Returns an OpenID4VCI credential offer URI. See https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#section-10.1

Analytic events

  • OPEN_ID_OFFER_CREATE_START
  • OPEN_ID_OFFER_CREATE_SUCCESS
  • OPEN_ID_OFFER_CREATE_FAIL
Authorizations:
bearerAuthOpenIdCredentials
Request Body schema: application/json
credentials
required
Array of strings

This array includes a list of identifiers for credentials that will be included in the credential offer. These identifiers are the id elements returned in the response when you create a credential configuration. To issue multiple credential profiles of the same credential in a single flow, include all the required credential configuration id elements in the request payload.

object

Specifies a list of additional request parameters that the wallet can include in the authentication request.

Responses

Request samples

Content type
application/json
{
  • "credentials": [
    ],
  • "request_parameters": {
    }
}

Response samples

Content type
application/json
{
  • "uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fmyissuer.example.com%22%2C%22credentials%22%3A%5B%22707e920a-f342-443b-ae24-6946b7b5033e%22%5D%2C%22request_parameters%22%3A%7B%22login_hint%22%3A%22user%40example.com%22%2C%22prompt%22%3A%22login%22%7D%7D"
}

Retrieve OpenID4VCI issuer metadata

Returns OpenID4VCI issuer metadata. This is the standard OpenID4VCI Well Known endpoint for your tenant.

This endpoint is unprotected, public facing and can be deterministically found at the root of the tenant subdomain or alias by any party wishing to discover the OpenID4VCI capabilities.

Responses

Request samples 

curl --request GET \
  --url https://{tenantName}.{region}.mattr.global/.well-known/openid-credential-issuer \
  --header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "issuer": "http://example.com",
  • "authorization_endpoint": "http://example.com",
  • "token_endpoint": "http://example.com",
  • "scopes_supported": [
    ],
  • "response_types_supported": [
    ],
  • "response_modes_supported": [
    ],
  • "grant_types_supported": [
    ],
  • "code_challenge_methods_supported": [
    ],
  • "credential_issuer": "http://example.com",
  • "credential_endpoint": "http://example.com",
  • "credentials_supported": [
    ],
  • "mdoc_iacas_uri": "http://example.com"
}

Users

Search users

Returns a list of users from the tenant that match the provided search criteria.

Analytic events

  • USER_SEARCH_START
  • USER_SEARCH_SUCCESS
  • USER_SEARCH_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The search criteria

claims
object

Filter users by claims. Nestsed objects are supported. Text values must be an exact match.

object

Filter users by their unique identifier in the configured Authentication Provider.

limit
number [ 1 .. 1000 ]

Range size of returned entries, default 100

cursor
string

Starting point for the range of entries

Responses

Request samples

Content type
application/json
{
  • "claims": {
    },
  • "authenticationProvider": {
    },
  • "limit": 100,
  • "cursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h"
}

Response samples

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

Retrieve all users

Returns a list of all users on your tenant.

Analytic events

  • USER_RETRIEVE_LIST_START
  • USER_RETRIEVE_LIST_SUCCESS
  • USER_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned entries, default 100

Example: limit=2
cursor
string

Starting point for the range of entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples 

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

Response samples

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

Retrieve a user

Retrieve an existing user by providing its ID.

  • USER_RETRIEVE_START
  • USER_RETRIEVE_SUCCESS
  • USER_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

User ID

Example: 8241400f-de3b-42c5-ad7c-8a380039e796

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba",
  • "claims": {
    }
}

Update a User

Updates an existing user by providing its ID.

  • USER_UPDATE_START
  • USER_UPDATE_SUCCESS
  • USER_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

User ID

Example: 8241400f-de3b-42c5-ad7c-8a380039e796
Request Body schema: application/json

Update a User

claims
required
object

User claims to be updated.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "0c3fad74-a8df-4a2d-8e75-f2d356b413ba",
  • "claims": {
    }
}

Delete a user

Deletes a user and removes any persisted data related to them by providing the user ID.

Any credentials issued to the user remain valid even after the user is deleted.

Analytic events

  • USER_DELETE_START
  • USER_DELETE_SUCCESS
  • USER_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

User ID

Example: 8241400f-de3b-42c5-ad7c-8a380039e796

Responses

Request samples 

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

Response samples

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

Retrieve all user credentials data

Returns a list of metadata for all the credentials referenced by the provided userId.

Authorizations:
bearerAuth
path Parameters
userId
required
string <uuid>

User ID

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

Responses

Request samples 

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

Response samples

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

OIDC Verifier Auth

Well Known OpenId Configuration

The standard OpenID Connect Well Known configuration metadata endpoint.

This endpoint is unprotected, public facing and can be used by any party wishing to discover the OpenID Connect capabilities.

path Parameters
id
required
string <uuid>

Verifier ID

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

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/ext/oidc/v1/verifiers/:id/.well-known/openid-configuration'

Response samples

Content type
application/json
{}

Retrieve Token

OIDC Token endpoint

The OpenId Connect /token endpoint is used to obtain the access_token and id_token by presenting a valid authorization code

Analytic events

  • OIDC_VERIFIER_AUTH_START
  • OIDC_VERIFIER_AUTH_SUCCESS
  • OIDC_VERIFIER_AUTH_FAIL
path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
Request Body schema: application/x-www-form-urlencoded

Token endpoint request

One of
string
client_secret
string
grant_type
string
code
string
redirect_uri
string <uri>

Responses

Request samples

Content type
application/x-www-form-urlencoded
No sample

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "bearer",
  • "refresh_token": "string",
  • "expires_in": 0,
  • "id_token": "string"
}

OIDC Verifiers

Create an OIDC Verifier

Creates a new OIDC Credential Verifier on the tenant.

Once created, this OIDC Verifier is publicly available on its /.well-known/openid-configuration path. The Authorization header is not required as it is intended for OIDC Client applications to resolve.

Analytic events

  • OIDC_VERIFIER_CREATE_START
  • OIDC_VERIFIER_CREATE_SUCCESS
  • OIDC_VERIFIER_CREATE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The verifier payload

verifierDid
required
string

Specifies the DID where the verifiable presenation will be sent to.

presentationTemplateId
required
string <uuid>

References the unique idetnifier of a Presentation Request Template that will be used by this verifier to create presentation requests.

required
Array of objects

As part of verifying a credential, the OIDC client initiates the request expecting a standard OIDC ID Token. However, as the digital wallet provides the credential in JSON-LD terms, it is required to map JSON-LD claims to OpenID Connect terms.

  • Currently the platform only supports schema.org for data vocabularies.
  • Make sure to use http:// and not https:// when entering jsonLdFqn values for schema.org. Otherwise you may not get the claims returned in your ID Token.
  • Standard OIDC claims are available on the Common Credential to OIDC Claim mappings page, so you can just copy & paste into your payload.
includePresentation
boolean

When set to true, the generated id_token will include the original presentation from the wallet.

Responses

Request samples

Content type
application/json
{
  • "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  • "presentationTemplateId": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "claimMappings": [],
  • "includePresentation": true
}

Response samples

Content type
application/json
{
  • "id": "41458e5a-9092-40b7-9a26-d4eb43c5792f",
  • "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  • "presentationTemplateId": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "claimMappings": [],
  • "includePresentation": true
}

Retrieve all OIDC Verifiers

Returns a list of all OIDC Verifiers on the tenant.

Analytic events

  • OIDC_VERIFIER_RETRIEVE_LIST_START
  • OIDC_VERIFIER_RETRIEVE_LIST_SUCCESS
  • OIDC_VERIFIER_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned verifier entries, default 100

Example: limit=2
cursor
string

Starting point for the range of verifier entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples 

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

Response samples

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

Retrieve an OIDC Verifier

Retrieves an existing OIDC Verifier by providing its ID.

Analytic events

  • OIDC_VERIFIER_RETRIEVE_START
  • OIDC_VERIFIER_RETRIEVE_SUCCESS
  • OIDC_VERIFIER_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Verifier ID

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

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "41458e5a-9092-40b7-9a26-d4eb43c5792f",
  • "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  • "presentationTemplateId": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "claimMappings": [],
  • "includePresentation": true
}

Update an OIDC Verifier

Updates an existing OIDC Verifier by providing its ID.

Analytic events

  • OIDC_VERIFIER_UPDATE_START
  • OIDC_VERIFIER_UPDATE_SUCCESS
  • OIDC_VERIFIER_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Verifier ID

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

Update a verifier

verifierDid
required
string

Specifies the DID where the verifiable presenation will be sent to.

presentationTemplateId
required
string <uuid>

References the unique idetnifier of a Presentation Request Template that will be used by this verifier to create presentation requests.

required
Array of objects

As part of verifying a credential, the OIDC client initiates the request expecting a standard OIDC ID Token. However, as the digital wallet provides the credential in JSON-LD terms, it is required to map JSON-LD claims to OpenID Connect terms.

  • Currently the platform only supports schema.org for data vocabularies.
  • Make sure to use http:// and not https:// when entering jsonLdFqn values for schema.org. Otherwise you may not get the claims returned in your ID Token.
  • Standard OIDC claims are available on the Common Credential to OIDC Claim mappings page, so you can just copy & paste into your payload.
includePresentation
boolean

When set to true, the generated id_token will include the original presentation from the wallet.

Responses

Request samples

Content type
application/json
{
  • "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  • "presentationTemplateId": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "claimMappings": [],
  • "includePresentation": true
}

Response samples

Content type
application/json
{
  • "id": "41458e5a-9092-40b7-9a26-d4eb43c5792f",
  • "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  • "presentationTemplateId": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "claimMappings": [],
  • "includePresentation": true
}

Delete an OIDC Verifier

Deletes an existing OIDC Verifier by providing its ID.

Analytic events

  • OIDC_VERIFIER_DELETE_START
  • OIDC_VERIFIER_DELETE_SUCCESS
  • OIDC_VERIFIER_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Verifier ID

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

Responses

Request samples 

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

Response samples

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

OIDC Verifier Client

Configure an OIDC Client

Configures an OIDC Verifier Client on your tenant.

In order to verify a credential using an OpenID Connect Authorization Code Flow, you need to set up an OIDC Client application. This is the client that will engage with your configured OIDC Verifier to inititate the verification workflow. There is a list of OIDC Client apps, also known as Relying Party Libraries, on the OpenID website. Pick one which you feel comfortable with.

When dealing with personal identity information it is strongly recommended to follow the Authorization Code Flow which ensures sensitive data is transmitted via the /token endpoint back-channel.

Analytic events

  • OIDC_VERIFIER_CLIENT_CREATE_START
  • OIDC_VERIFIER_CLIENT_CREATE_SUCCESS
  • OIDC_VERIFIER_CLIENT_CREATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Verifier ID

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

The client payload

name
required
string

Insert a meaningful name for your OIDC Client.

redirectUris
required
Array of strings <uri>

This array can include a list of URLs. One of the URIs in that list must match the callback URI configured for your OIDC Client for the Authorization Request:

  • Must be a valid URL.
  • Must use the HTTPS protocol.
  • Must not be an IP address.
  • Must not include query parameters.
  • For testing, it’s okay to add a localhost uri like https://localhost:9090/callback
responseTypes
Array of strings

Determines the authorization processing flow.

grantTypes
Array of strings

OAuth Grant Type.

tokenEndpointAuthMethod
string

OAuth Token Endpoint Authentication Method.

idTokenSignedResponseAlg
required
string

Algorithm must match configured jwks. Defaults to ES256.

applicationType
string
logoUri
string <uri>

The logo to display above the QR code.

Responses

Request samples

Content type
application/json
{
  • "name": "OIDC Client for the verifier",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web",
  • "logoUri": "https://example.com/logo.png"
}

Response samples

Content type
application/json
{
  • "id": "da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d",
  • "secret": "H2epdcmNJ46hXJo5opdzvhbZK9W2ZGPkQh.E",
  • "name": "OIDC Client for the verifier",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web",
  • "logoUri": "https://example.com/logo.png"
}

Retrieve all OIDC Clients

Returns a list of all OIDC Verifier Clients on the Tenant.

Analytic events

  • OIDC_VERIFIER_CLIENT_RETRIEVE_LIST_START
  • OIDC_VERIFIER_CLIENT_RETRIEVE_LIST_SUCCESS
  • OIDC_VERIFIER_CLIENT_RETRIEVE_LIST_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
query Parameters
limit
number [ 1 .. 1000 ]

Range size of returned client entries, default 100

Example: limit=2
cursor
string

Starting point for the range of client entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples 

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

Response samples

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

Retrieve an OIDC Client

Retrieves an existing OIDC Verifier Client by providing its ID.

Analytic events

  • OIDC_VERIFIER_CLIENT_RETRIEVE_START
  • OIDC_VERIFIER_CLIENT_RETRIEVE_SUCCESS
  • OIDC_VERIFIER_CLIENT_RETRIEVE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

OIDC Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
clientId
required
string <uuid>

OIDC Verifier Client ID

Example: da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.vii.{region}.mattr.global/ext/oidc/v1/verifiers/:id/clients/:clientId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d",
  • "secret": "H2epdcmNJ46hXJo5opdzvhbZK9W2ZGPkQh.E",
  • "name": "OIDC Client for the verifier",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web",
  • "logoUri": "https://example.com/logo.png"
}

Update an OIDC Client

Updates an existing OIDC Verifier Client by providing its ID.

Analytic events

  • OIDC_VERIFIER_CLIENT_UPDATE_START
  • OIDC_VERIFIER_CLIENT_UPDATE_SUCCESS
  • OIDC_VERIFIER_CLIENT_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

OIDC Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
clientId
required
string <uuid>

OIDC Verifier Client ID

Example: da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d
Request Body schema: application/json

Update a client

name
required
string

Insert a meaningful name for your OIDC Client.

redirectUris
required
Array of strings <uri>

This array can include a list of URLs. One of the URIs in that list must match the callback URI configured for your OIDC Client for the Authorization Request:

  • Must be a valid URL.
  • Must use the HTTPS protocol.
  • Must not be an IP address.
  • Must not include query parameters.
  • For testing, it’s okay to add a localhost uri like https://localhost:9090/callback
responseTypes
Array of strings

Determines the authorization processing flow.

grantTypes
Array of strings

OAuth Grant Type.

tokenEndpointAuthMethod
string

OAuth Token Endpoint Authentication Method.

idTokenSignedResponseAlg
required
string

Algorithm must match configured jwks. Defaults to ES256.

applicationType
string
logoUri
string <uri>

The logo to display above the QR code.

Responses

Request samples

Content type
application/json
{
  • "name": "OIDC Client for the verifier",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web",
  • "logoUri": "https://example.com/logo.png"
}

Response samples

Content type
application/json
{
  • "id": "da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d",
  • "secret": "H2epdcmNJ46hXJo5opdzvhbZK9W2ZGPkQh.E",
  • "name": "OIDC Client for the verifier",
  • "redirectUris": [],
  • "responseTypes": [
    ],
  • "grantTypes": [
    ],
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "idTokenSignedResponseAlg": "ES256",
  • "applicationType": "web",
  • "logoUri": "https://example.com/logo.png"
}

Delete an OIDC Client

Deletes an existing OIDC Verifier Client by providing its ID.

Analytic events

  • OIDC_VERIFIER_CLIENT_DELETE_START
  • OIDC_VERIFIER_CLIENT_DELETE_SUCCESS
  • OIDC_VERIFIER_CLIENT_DELETE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

OIDC Verifier ID

Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f
clientId
required
string <uuid>

OIDC Verifier Client ID

Example: da9bb6e4-c9ae-4468-b6ac-72b90d6efd5d

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.vii.{region}.mattr.global/ext/oidc/v1/verifiers/:id/clients/:clientId' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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