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

Platform Core API (v2.0.0)

Download OpenAPI specification:Download

E-mail: support@mattr.global

Introduction

The Platform Core APIs define a set of capabilities that can be used to manage a MATTR VII tenant.

The API can be used to manage Decentralised Identifiers, issue Credentials directly or using OpenID Connect flows, and verify Messages signed with DIDs.

Refer to our API Changelog to see changes from previous versions.

Getting Started with our APIs

Construct your Tenant URL

As a MATTR VII user, you are provided with the requisite tenant details via an out-of-band onboarding process as follows:

{
"tenantSubdomain": "YOUR_TENANT_SUBDOMAIN",
"tenantId": "YOUR_TENANT_ID",
"url": "YOUR_AUTH_URL",
"audience": "YOUR_AUDIENCE_URL",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}

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

Use the YOUR_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 different APIs.

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 use pagination that can be controlled by a cursor method using the cursor and limit query parameters.

Example on Retrieve List of Credentials

GET https://{tenant-url}/core/v2/credentials
?limit=100
&cursor=Y3JlYXRlZEF0PTIwMjAtMTAtMDhUMjMlM0ExMyUzQTE3Ljg5NtZGUxZWEyNzQ4MWI4
  • The nextCursor is found at the start of each returned range of credential entries and identifies the last object in the list.
  • The limit determines how many entries are returned in that request, with a maximum value of 1000.

Requesting a page after the last value in the list will return an empty data object.

{
"data": []
}

Not using a query parameter defaults the response to return the first range of credential 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 call to the auth provider and receive a bearer token. This token is then used in an authorization header on all calls identified as requiring bearerAuth (this is required for the majority of management operations).

bearerAuth

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

bearerAuthOpenIdCredentials

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Security

Create API Auth Token

Authorization endpoint for gaining token used for API requests requiring bearerAuth.

You will be provided the required client_id and client_secret as part of onboarding, as well as your authentication server and audience.

Request Body schema: application/json
client_id
required
string
client_secret
required
string
audience
required
string
grant_type
required
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "htf792W4p4MedZbnoWAs51EfqUt4d2",
  • "client_secret": "d3fYDX7FjPg1D1h2viARXsolPByQ9vMfg8LHylBy8F4s5KJLB4HhHGOxxqJnSj3G",
  • "audience": "https://vii.mattr.global",
  • "grant_type": "client_credentials"
}

Response samples

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

Custom Domain

Create custom domain

A custom domain allows the display of your credentials or presentation requests to be rendered under the domain your preference as a tenant on the MATTR VII platform.

The verifiable custom domain can be mapped with that of the issuer or verifier stated in a credential or presentation and allow for the following attributes to be defined and returned:

  • Organization Name
  • Domain Name
  • Logo

Returns

On Success, the response from the endpoint always include the Custom Domain

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

Name of the custom domain

logoUrl
required
string

Url for the domain logo

domain
required
string

New domain

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,
  • "verifiedAt": null
}

Retrieve custom domain

Retrieve the custom domain information and it's verification status for your MATTR VII tenant.

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}.au01.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": false,
  • "verifiedAt": null
}

Delete custom domain

Delete the custom domain.

By deleting your existing custom domain it will break the linkage with any credentials issued under the custom domain, in turn causing issues when holders of those credentials go to present them.

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

Update the custom domain.

Follows the same structure as the Create a Custom Domain endpoint.

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

Name of the custom domain

logoUrl
required
string

Url for the domain logo

domain
required
string

New domain

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 custom domain by examining the TXT record of the domain.

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}.au01.mattr.global/core/v1/config/domain/verify' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Analytics

List events

Returns a list of events for the tenant.

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

Authorizations:
bearerAuth
query Parameters
ids
Array of Array of strings

List of event IDs used for event filtering

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

List of request IDs used for event filtering

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

List of categories used for event filtering. Uses an "OR" operation with "types". For example, (categories OR types) AND requestIds

Example: categories=dcc
types
Array of Array of strings

List of types used for event filtering. Uses an "OR" operation with "categories". For example, (categories OR types) AND requestIds

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

Starting date (inclusive) in ISO-8601 format used for event filtering

Example: dateFrom=2023-06-01T02:45:44.087Z
dateTo
string <date-time>

Ending date (inclusive) in ISO-8601 format used for event filtering

Example: dateTo=2023-06-30T23:59:59.999Z
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}.au01.mattr.global/core/v1/analytics/events?ids=e4c387e7-3e63-40f4-9a38-062aaae9ee50&requestIds=e4c387e7-3e63-40f4-9a38-062aaae9ee50&categories=dcc&types=DCC_SIGN_START&dateFrom=2023-06-01T02%3A45%3A44.087Z&dateTo=2023-06-30T23%3A59%3A59.999Z&limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

DIDs

Well known DID configuration

Returns a list of Decentralized Identifier (DID) Configuration entries from the tenant.

See https://identity.foundation/.well-known/resources/did-configuration/

These entries are automatically configured for all DIDs created by the tenant and is used for any party wanting to establish the relationship between domain ownership and the DIDs by exposing cryptographic proofs.

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 domain to DID relationship.

Responses

Request samples 

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

Response samples

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

Create a DID

Takes a supported DID Method and generates keys and associated information for a new DID and registers the DID Document if applicable.

Methods supported:

  • key
  • web

Options: The options parameter is used to define further configuration when creating the DID, the available options vary between methods.

Note: W3C DIDs are an emerging standard at the W3C, DIDs issued during a trial on the MATTR VII platform may be subject to change, as you move into production workloads please get in touch to discuss your needs.

Creating did:key

A DID with a DID method of key can be created.

If no options are provided, a DID will be created with an Ed25519 key type.

If the key type in options is set to Bls12381G2 a DID will be created with a BLS key type which supports BBS signatures for issuing ZKP-enabled credentials.

A DID Key created with an experimental Bls12381G2 key type can only be used for issuing credentials.

Creating did:web

A DID with a DID method of web can be created by specifying the domain where the DID document is going to be hosted in the options body.

If the keyType in options is not provided, a DID will be created with Ed25519, Bls12381G2, and P-256 key types.

If the keyType in options is set to P-256, then this DID can only be used to create Compact Credentials, NOT Web Credentials.

The returned initial DID Document then needs to be hosted so that it is accessible from the domain provided in the options, e.g. https://mattr.global/.well-known/did.json.

When the DID Document is not available for download from the domain, the Registration Status of the DID is PROCESSING.

Once the DID Document can be downloaded from the domain, the Registration Status will be COMPLETED.

Note that the tenant will be able to prove ownership of the keys associated with the did:web DID Document through the well-known endpoint, i.e. https://tenant.vii.mattr.global/.well-known/did-configuration, while the DID Document hosted on the domain links the DID to a domain.

Returns

The DID, associated metadata and registration status.

Unsupported Methods result in a 400 response with an "Invalid value" message.

Analytics 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
Enum: "key" "web"
options
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:organization.com",
  • "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.

Analytics 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}.au01.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

When the DID is retrieved by the DID provided in the path, the DID Document is also attempted to be resolved by using the DID method and method identifier, this may involve a network call depending on the method involved.

Example:

did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9 - the public key is encapsulated in the DID did:web:mattr.global - will be resolved by accessing the /.well-known/did.json of the domain

Returns

If the DID Document is publicly resolvable it is returned along with meta-data already held about the DID by the tenant;

Analytics events

  • DID_RETRIEVE_START
  • DID_RETRIEVE_SUCCESS
  • DID_RETRIEVE_FAIL
  • didDocument: See our tutorials on MATTR Learn to understand more about the anatomy of the DID Document for each method.
  • registrationStatus: Ledger-based DIDs may incur a lag in processing to the ledger. Also for DIDs that require additional actions (e.g. did:web) this status will be update from PROCESSING to COMPLETED once publicly resolvable.
  • localMetadata: This includes the initial DID document that the platform expects to find publicly resolvable.
Authorizations:
bearerAuth
path Parameters
id
required
string <did>

DID

Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "did": "did:web:organization.com",
  • "registrationStatus": "COMPLETED",
  • "localMetadata": {
    }
}

Delete a DID

Deletes a DID and all associated metadata including the Private keys from the platform and KMS. For ledger-based DIDs the public DID Document will still be available. For did:web you can remove the did.json from your hosted domain.

Analytics 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}.au01.mattr.global/core/v1/dids/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Messaging

Sign a message

Creates a signed message in the form of a JWS (JSON Web Signature) using the a specific Key from the DID (Decentralized Identifier) supplied in the request.

didUrl must be a reference to a key that supports signing. Use the authentication key value from the DID Document. Simply put, from your DID document, you can find it in DID.localMetadata.initialDidDocument.authentication[0]

{
    "did": "did:web:organization.com",
    "registrationStatus": "COMPLETED",
    "localMetadata": {
        "keys": [
            {
                "didDocumentKeyId": "did:web:organization.com#2vcj3MjR4d",
                "kmsKeyId": "a0cba537-ffe1-486d-aedd-6ead80e75519"
            },
            {
                "didDocumentKeyId": "did:web:organization.com#CU6dJt9p8t",
                "kmsKeyId": "250c4e1f-bae3-44ca-9f4e-4f7ff15851e2"
            }
        ],
        "registered": 1674421454614,
        "initialDidDocument": {
            "@context": [
                "https://w3.org/ns/did/v1",
                "https://w3id.org/security/suites/x25519-2019/v1",
                "https://w3id.org/security/suites/ed25519-2018/v1"
            ],
            "id": "did:web:organization.com",
            "verificationMethod": [
                {
                    "id": "did:web:organization.com#2vcj3MjR4d",
                    "controller": "did:web:organization.com",
                    "type": "Ed25519VerificationKey2018",
                    "publicKeyBase58": "2vcj3MjR4dSKq5asFQ9oor7iZsqTKTfBpjLHgaP15Y24"
                }
            ],
            "authentication": [                     
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "assertionMethod": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "capabilityDelegation": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "capabilityInvocation": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "keyAgreement": [
                {
                    "id": "did:web:organization.com#CU6dJt9p8t",
                    "controller": "did:web:organization.com",
                    "type": "X25519KeyAgreementKey2019",
                    "publicKeyBase58": "CU6dJt9p8twE4hmyGVFbVpUMmu6G732bVgD1tNupwYY7"
                }
            ]
        }
    }
}

Returns

A JWS in compact serialization form signed by the did supplied 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 keyId that will be used to sign the message with.

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

Provide a signed payload in the form of a JWS (JSON Web Signature) that has been signed by a DID (Decentralized Identifier) and get a response indicating if the signature verification was successful and the DID that was used to originally sign the payload.

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.

Returns

Indicates if the JWS payload was untampered and that the signature is valid by verifying that the kid in the JWS header is the same as the iss value in the Request Object, which could for instance be the Subject DID. The DID used is returned as both the full didUrl including fragment pointer to the DID Document and the did which can be used for Credential creation.

Analytic events

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

JWS to verify

jws
string

Compact form of JWS

Responses

Request samples

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

Response samples

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

Encrypt a message

Encrypts a payload using a JWM format.

The senderDidUrl must be a reference to a key that supports key agreement. Use the id value from the keyAgreement list in the DID Document.

Simply put, you can find the value to use as senderDidUrl from DID.localMetadata.initialDidDocument.keyAgreement[0].id

{
    "did": "did:web:organization.com",
    "registrationStatus": "PROCESSING",
    "localMetadata": {
        "keys": [
            {
                "didDocumentKeyId": "did:web:organization.com#2vcj3MjR4d",
                "kmsKeyId": "a0cba537-ffe1-486d-aedd-6ead80e75519"
            },
            {
                "didDocumentKeyId": "did:web:organization.com#CU6dJt9p8t",
                "kmsKeyId": "250c4e1f-bae3-44ca-9f4e-4f7ff15851e2"
            }
        ],
        "registered": 1674421454614,
        "initialDidDocument": {
            "@context": [
                "https://w3.org/ns/did/v1",
                "https://w3id.org/security/suites/x25519-2019/v1",
                "https://w3id.org/security/suites/ed25519-2018/v1"
            ],
            "id": "did:web:organization.com",
            "verificationMethod": [
                {
                    "id": "did:web:organization.com#2vcj3MjR4d",
                    "controller": "did:web:organization.com",
                    "type": "Ed25519VerificationKey2018",
                    "publicKeyBase58": "2vcj3MjR4dSKq5asFQ9oor7iZsqTKTfBpjLHgaP15Y24"
                }
            ],
            "authentication": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "assertionMethod": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "capabilityDelegation": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "capabilityInvocation": [
                "did:web:organization.com#2vcj3MjR4d"
            ],
            "keyAgreement": [
                {                        
                    "id": "did:web:organization.com#CU6dJt9p8t",
                    "controller": "did:web:organization.com",
                    "type": "X25519KeyAgreementKey2019",
                    "publicKeyBase58": "CU6dJt9p8twE4hmyGVFbVpUMmu6G732bVgD1tNupwYY7"
                }
            ]
        }
    }
}

Analytic events

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

Encryption params

senderDidUrl
required
string
recipientDidUrls
required
Array of strings
payload
required
object

Responses

Request samples

Content type
application/json
{
  • "senderDidUrl": "did:web:organization.com#CU6dJt9p8t",
  • "recipientDidUrls": [
    ],
  • "payload": {}
}

Response samples

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

Decrypt a message

Decrypt a message where the tenant manages the Keys for the recipientDidUrl

The jwe attribute for request body can be extracted from the jwe attribute of the response body you get from POST core/v1/messaging/encrypt (Encrypt a message). You don't need to construct the value for jwe by yourself.

Alternatively, the jwe field also accepts a jwe string. You can obtain it by encoding your jwe object using Base64 encoding method.

You can obtain a JWE string (In Compact Serialisation format) by 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)

For reference, this is the open-standard for JWE Compact Serialisation.

Analytic events

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

Decryption params

required
string or EncryptedMessage (object)

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

Send an encrypted JWM format DIDComm message to a DID service endpoint.

In order to successfully route messages to their intended recipients the endpoint will resolve a public DID Document and look-up the service endpoint.

This endpoint only accepts Encrypted JWM payloads to ensure that messages sent for recipients are encrypted-at-rest whilst in messaging inboxes. The JWM should be encrypted for the recipient based on a key available in the 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

JWE message

Responses

Request samples

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

Response samples

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

Create an inbox

An inbox will hold messages for DIDs that are registered with the inbox

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

Responses

Request samples

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

Response samples

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

List inboxes

Returns a list of all registered inboxes for 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}.au01.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

Returns a single inbox based on the Inbox 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}.au01.mattr.global/core/v1/messaging/inboxes/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Update an inbox

Update the inbox configurations

Authorizations:
bearerAuth
path Parameters
id
required
string

Inbox ID

Request Body schema: application/json

Update Inbox configuration

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": "string",
  • "name": "string"
}

Delete an inbox

Deletes a specific inbox

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

'This endpoint is responsible for registering DIDs to a specific Inbox. Currently, DID registration with inboxes is 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

Inbox ID

Request Body schema: application/json

DID registration information

did
required
string
jwt
string

Responses

Request samples

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

Response samples

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

List DIDs in an inbox

Returns a list of all DIDs for the specific 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

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

Unregister a DID from a specific 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

Inbox ID

did
required
string

DID

Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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 messages from an inbox

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

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

Returns an inbox message

Analytic events

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

Inbox ID

messageid
required
string

Message ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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 from inbox

Deletes an inbox message

Analytic events

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

Inbox ID

messageid
required
string

Message ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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 a webhook

Create a new webhook for this tenant.

The list of events are the names of the events that will trigger the request to the designated url.

The url entered is where the request will be sent.

Note: the URL has to have https:// as its prefix.

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

List of events that cause the webhook to fire

Items Value: "OidcIssuerCredentialIssued"
url
required
string <uri>

The destination url for the webhook

disabled
boolean

Whether or not the webhook is disabled

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
}

Get a list of webhooks

Retrieve a list of webhooks for this 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}.au01.mattr.global/core/v1/webhooks?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Get a webhook

Retrieve a specific webhook from this tenant.

Analytic events

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

Webhook ID

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

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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 a webhook

Update the following attributes on an existing webhook for this tenant.

events an array of events that will trigger the webhook to the designated url.

url for where the webhook will send the event payload.

disabled that specifies whether or not the webhook will listen for events.

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 a Webhook

events
required
Array of strings

List of events that cause the webhook to fire

Items Value: "OidcIssuerCredentialIssued"
url
required
string <uri>

The destination url for the webhook

disabled
boolean

Whether or not the webhook is disabled

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
}

Remove a webhook

Removes a specific webhook from this tenant.

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}.au01.mattr.global/core/v1/webhooks/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Get a list of webhook JWKs

Retrieve a list of webhook JWKs for this tenant.

Authorizations:
bearerAuth

Responses

Request samples 

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

Response samples

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

Credentials

Sign a Web Semantic Credential

Create a Web Semantic Credential by providing a valid payload.

Any additional claims to be represented by the credential should be added in the credentialSubject object.

A separate option can be provided to specify if the credential should be revocable. This is set to false by default.

The persist field determines whether or not the contents of the credential should be stored in MATTR platform in addition to the metadata. This is set to false by default.

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

Proof type for the credential. Issuer DID must contain a key that supports the corresponding signing capability.

Enum: "Ed25519Signature2018" "BbsSignature2022"
tag
string [ 1 .. 1024 ] characters

An optional tag to filter by, will not be part of the issued credential

persist
boolean
Default: false

Flag to indicate whether the full credential should be stored in the platform.

revocable
boolean
Default: false

Flag to indicate if the credential needs to support revocation.

Responses

Request samples

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

Response samples

Content type
application/json
{}

Retrieve list of credential data

Returns a list of all credential data for the existing credentials stored in the tenant.

In the list

Inside the data array, there is a body for each credential issued on the platform, in addition to the id the body will contain optionally added meta-data and may contain the entire credential contents if persist was invoked during credential creation.

Credentials issued via the OpenID4VCI protocol are set not to be persisted by default.

Pagination

Pagination can be controlled by a cursor method using the cursorand limit query parameters. The nextCursor is found at the start of each returned range of credential entries and the limit determines how many entries are returned in that request, with a maximum value of 1000.

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

The optional tag filter or the Credential type can be used to retrieve credential data.

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

The optional external reference to filter on

Example: tag=identifier123
type
string

The 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}.au01.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

Get data for the existing credential using a credential ID.

In addition to the id the body will contain optionally added meta-data and may contain the entire credential contents if persist was invoked during credential creation.

Credentials issued via the OpenID4VCI protocol are set not to be persisted by default.

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}.au01.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
{}

Remove credential data

Remove all stored credential data for the existing credential from the tenant using its ID.

The entire entry including metadata and the credential contents is removed from the system and cannot be recovered. If the credential is revocable, it will be permanently revoked.

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}.au01.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 sending the payload and specifying options that could determine the resulting verification checks.

Standard checks performed on all verification requests:

  • Fetch the public key from the did.json of the issuer did and validate the proof signature.

Optional parameter checks:

  • assertExpiry if set to true and the credential has an expiry date set, this will be checked and verification will fail if the expiry date has passed.
  • checkRevocation if the provided credential contains a revocation status list, this will be checked and 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)

To supply a value for this field, you can find it by looking up the credential attribute from the response body of the sign endpoint.

assertExpiry
boolean
Default: true

Flag to indicate if verification should fail when expiry date has passed.

checkRevocation
boolean
Default: true

Flag to indicate if verification should fail when credential has been revoked.

Responses

Request samples

Content type
application/json
{}

Response samples

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

Revocation

Set credential revocation status

A credential can be revoked by setting the revocation status.

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

true if the credential is revoked, false otherwise

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

Retrieve the revocation status of a certain credential.

Returns

The revocation status of the credential

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

Retrieve the revocation list that contains the revocation status of a number of credentials.

Returns

The revocation list

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}.au01.mattr.global/v2/revocation-lists/:id'

Response samples

Content type
application/json
{}

Create a revocation message payload

Create a payload that can form a message in the JWM format that can be used in sending notifications to subjects based on the revocation status of their issued credentials.

  • Use a DID setup on the tenant as the from value, this should be a DID with a key type suitable for messaging (not a BLS key type)
  • Include a SubjectDID as the to value - this value is only used in the message construction, it should be the same value as the intended recipient.

To send a notification to the Subject DID holder, use the payload with the /messaging/encrypt and /messaging/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>

Credential ID

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

Create a JWM message payload

from
required
string non-empty

DID on the tenant used in a message

to
required
Array of strings

List of SubjectDIDs

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

Presentations

Create a presentation template

A Presentation Request template defines which credentials are required for presentation. This is used to create the actual Presentation Request, which is used by the mobile wallet to select which credential it should display to the holder, asking for confirmation to be used in the Presentation to be sent.

Creating the payload

The domain value must always match the subdomain of the tenant being used.

The name value is a convenience attribute for quickly determining the intended purpose of a created template.

The Presentation Request query follows the Verifiable Presentation Request Specification. Query can accept an array of types, which makes is possible to construct complex presentation requests from the template, however creating a valid Presentation Template does not ensure that logically valid Presentation Request is created or that a credential holder would be able to satisfy the request. The following query methods have been enabled:

  • Query by Example
  • Query by Frame
  • DID Auth

Query by Example

This is a basic form of requesting credential information, it is possible to limit the request based on:

  • Credential Type - based on the type of the credential
  • Specific Trusted Issuer DIDs - an array of DIDs that the credential must have been issued by one of.

Query by Frame

Used primary for requesting specific claims from ZKP-enabled credentials, only the claims requested in the frame will be derived and sent in the presentation.

  • Credential Type - If an array should match the exact type used in the Credential otherwise a string is required to be VerifiableCredential.
  • CredentialSubject - request specific claims from a credential subject.
  • Specific Trusted Issuer DIDs - an array of DIDs that the credential must have been issued by one of, ensure this DID is of a BLS key type that has issued a ZKP-enabled credential.

DID Auth

The type of Template will result in a DID Auth flow resulting in just the Subject DID from the holder to be provided in the response to the Presentation Request.

  • DIDAuth

Returns

The successful response from the endpoint will include the Presentation Template ID. This UUID (presentation template ID) is required in OIDC Bridge Verifier instance setup and using the Verify using a Callback method.

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

Must match domain of the tenant

name
required
string

Internal descriptor only

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

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 a list of presentation templates

Returns a list of all existing Presentation Templates on the tenant.

Use the name value to determine the intended purpose of the templates.

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}.au01.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 providing a template 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}.au01.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

Delete an existing Presentation Template using a template 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}.au01.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 presentation template

Update an existing Presentation Template by using a template ID.

Follows the same structure as the 'Create a Presentation Template' endpoint.

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

Must match domain of the tenant

name
required
string

Internal descriptor only

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

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.

Creating the payload

A challenge can be used to correlate requests. The DID used is the Verifier DID to prove the authenticity of the Request to holders. Any callbackUrl provided will be called on receipt of the response to the Presentation Request. If no expiresTime is provided, a default of 5 minutes will be used.

Returns

The request object holds the Presentation Request in the form of a constructed JWM message.

The request needs to be signed and conveyed to the holder, using techniques like a QR, deeplink or encrypted and sent via a notification message.

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

Challenge can be used to match the response to a request

did
required
string

DID of the Verifier. You can find the DID from the following location within your DID document: DID.localMetadata.initialDocument.keyAgreement[0].id

templateId
required
string

ID of a Presentation Template

expiresTime
number

Unix timestamp in ms after which the request will be expired

callbackUrl
required
string <uri>

Endpoint that will receive the Verifiable Presentation

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 presentation

Use this endpoint to verify a Verifiable Presentation that has been generated by any platform that adheres to the W3C Verifiable Credential Data Model.

Provide a presentation in the Request.

If a challenge and/or domain is provided then this will be used for credential verification. If it is not provided then the challenge and/or domain within the presentation proof is used instead.

The platform will perform these checks:

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 Finally, a proof is valid for the holderDID for the Presentation.

Response

If all checks are passed then the verified boolean is true. Otherwise it returns false with a basic reason.

Further detailed reasons for verified false responses is a future roadmap item.

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

Convert a document like a JSON-LD Credential or a Verifiable Presentation into a CBOR-LD document, and vice versa.

This operation is in Technical Preview, you may experience some inconsistencies when converting linked-data documents between encoding formats and we may introduce breaking changes to this operation based on feedback.

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. The MATTR Verify CBOR-LD Presentation sample app can be used as an example of how to verify these presentations using the MATTR VII APIs.

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"
}

Web Semantic Credential Configuration

Create a Credential Configuration for a web semantic based credential

Create a new Configuration for a web semantic credential that will be issued by your tenant.

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

Name of the credential

description
string

Description of the credential

type
required
string [ 1 .. 1024 ] characters

Type for the credential, must be unique across credential configurations for the tenant, cannot contain whitespace, and must not be VerifiableCredential.

additionalTypes
Array of strings

Additional types to be included in the credential.

Array of strings or objects

Additional JSON-LD contexts to be included in the credential.

required
object

Includes issuer name and optional branding properties.

proofType
string

Proof type for the credential. Issuer DID must contain a key that supports the corresponding signing capability.

Enum: "Ed25519Signature2018" "BbsSignature2022"
object

Includes optional credential branding properties.

object

Claim mapping configuration to generate credential subject claims during issuance.

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

Indicates data persistence. When TRUE credential data and metadata are stored in the credential registry. When false only credential metadata is stored in the credential registry.

revocable
boolean
Default: true

Indicates whether the credential is revocable.

claimSourceId
string <uuid>

Claim Source Id

object

Optional field that specifies how long after issuance credentials generated using this configuration will expire.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Retrieve list of Credential Configurations for web semantic based credentials

Returns a list of all Credential Configurations under 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}.au01.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 Credential Configuration

Retrieve an existing Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Responses

Request samples 

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

Response samples

Content type
application/json
{}

Update a Credential Configuration

Update an already existing Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Update a Credential Configuration

name
required
string

Name of the credential

description
string

Description of the credential

type
required
string [ 1 .. 1024 ] characters

Type for the credential, must be unique across credential configurations for the tenant, cannot contain whitespace, and must not be VerifiableCredential.

additionalTypes
Array of strings

Additional types to be included in the credential.

Array of strings or objects

Additional JSON-LD contexts to be included in the credential.

required
object

Includes issuer name and optional branding properties.

proofType
string

Proof type for the credential. Issuer DID must contain a key that supports the corresponding signing capability.

Enum: "Ed25519Signature2018" "BbsSignature2022"
object

Includes optional credential branding properties.

object

Claim mapping configuration to generate credential subject claims during issuance.

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

Indicates data persistence. When TRUE credential data and metadata are stored in the credential registry. When false only credential metadata is stored in the credential registry.

revocable
boolean
Default: true

Indicates whether the credential is revocable.

claimSourceId
string <uuid>

Claim Source Id

object

Optional field that specifies how long after issuance credentials generated using this configuration will expire.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Remove a Credential Configuration

Remove an already exising Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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": [
    ]
}

Compact Credentials

Sign a Compact Credential

Create a Compact Credential by providing a valid payload.

The iss contains the DID of the issuer, this must be a did:web using a P-256 key type available on the tenant.

The nbf (not before), exp (expiry) and iat (issued at) are all dates expressed as a Unix timestamp in seconds that control the validity period of the credential once it has been issued.

aud and sub are optional fields in the credential. The sub attribute can be used if the credential only needs to contain a single claim, and that claim is unique and understood within the context of the issuer and the credential’s use.

Any additional claims to be represented by the credential should then be added in the payload object after the sub attribute.

A separate option can be provided to specify if the credential should be revocable, this is false by default.

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

Responses

Request samples

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

Response samples

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

Verify a compact credential

Verify a compact credential by sending the encoded payload and specifying options that could determine the resulting verification checks.

Standard checks performed on all verification requests:

  • Conformance of the string and encoded data, all compact credentials must be pre-fixed with csc/1
  • Decode the CWT structure and validate attributes
  • Fetch the public key from the did.json of the issuer did:web and validate the proof signature

Optional parameter checks:

  • trustedIssuers if provided will compare the iss field against the array of trusted issuers and only return verified if found in the array.
  • assertNotBefore is a Unix timestamp provided in seconds, verify will fail if the current time is before the nbf value
  • assertNotAfter is a Unix timestamp provided in seconds, verify will fail if the current time is after the exp value
  • checkRevocation if the provided compact credential contains a revocation status list, this will be checked and verify will fail if the credential has been set to 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

a compact credential encoded payload

trustedIssuers
Array of strings
assertNotBefore
boolean
Default: true
assertExpiry
boolean
Default: true
checkRevocation
boolean
Default: true

Responses

Request samples

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

Response samples

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

Remove credential metadata

Remove all stored credential metadata from a tenant for a specific credential using its ID. Note that only the metadata of revocable credentials or credentials issued through the OpenID4VCI flow is saved.

All credential metadata related to the issued credential is removed from the system and cannot be recovered. If the credential is revocable, it will be permanently revoked.

Authorizations:
bearerAuth
path Parameters
id
required
string

Credential ID

Responses

Request samples 

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

Response samples

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

Public revocation list discovery

Every revocable credential issued will reference a Revocation List, this is automatically created and held on the tenant for the Issuer.

The public revocation list endpoint can be obtained from the public revocation list discovery endpoint.

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}.au01.mattr.global/v2/credentials/compact/revocation-lists' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
[
  • {
    }
]

Public revocation list

The public endpoint that retrieves the revocation list that contains the revocation status of a number of credentials.

Analytic events

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

ID of the revocation list

Responses

Request samples 

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

Update revocation status

A credential can be revoked by setting isRevoked to true. The status can be set back to false to reactivate the credential.

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 ID of the credential - JTI

Request Body schema: application/json

Update revocation status

isRevoked
required
boolean

Responses

Request samples

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

Response samples

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

Retrieve revocation status

Retrieve the revocation status of a credential.

Authorizations:
bearerAuth
path Parameters
id
required
string

Unique ID of the credential - JTI

Responses

Request samples 

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

Response samples

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

Generate a QR Code

Generate a QR Code to represent a Compact Credential from the base32 encoded string provided as the payload and an optional width.

  • The maximum length of the payload is 3391 characters.

The width of the output QR code can be specified using the optional width parameter.

  • The maximum size of the width is 1000px. If not provided the QR code library will generate a QR code with optimised width based on the size of the payload in the request.

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 payload of the encoded compact credential

width
number

Width in pixels of the output png image

Responses

Request samples

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

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

Compact Credential Configuration

Create a Credential Configuration for a compact credential

Create a new Configuration for a compact credential that will be issued by your tenant.

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

Type for the credential, must be unique across credential configurations for the tenant, cannot contain whitespace, and must not be VerifiableCredential.

required
object

Claim mapping configuration to generate credential subject claims during issuance.

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

Indicates whether the credential is revocable.

claimSourceId
string <uuid>

Claim Source Id

object

Optional field that specifies how long after issuance credentials generated using this configuration will expire.

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 list of Credential Configurations for compact credentials

Returns a list of all Comapct Credential Configurations under 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}.au01.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 Credential Configuration

Retrieve an existing Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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 Credential Configuration

Update an already existing Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Update a Credential Configuration

type
required
string [ 1 .. 1024 ] characters

Type for the credential, must be unique across credential configurations for the tenant, cannot contain whitespace, and must not be VerifiableCredential.

required
object

Claim mapping configuration to generate credential subject claims during issuance.

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

Indicates whether the credential is revocable.

claimSourceId
string <uuid>

Claim Source Id

object

Optional field that specifies how long after issuance credentials generated using this configuration will expire.

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

Remove a Credential Configuration

Remove an already exising Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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 Credential PDF Template Management

Create PDF Template

Creates a custom PDF template based on composed .zip archive data. Each .zip archive should include:

  • A PDF template called template.pdf
  • Font files in a font directory
  • A JSON file called config.json describing fields, its validation rules and fonts.

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

List PDF Templates

Retrieves a list of all Compact Credential PDF templates available for use.

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}.au01.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 PDF Template

Update a PDF template based on uploaded .zip archive data.

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}.au01.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 PDF Template

Retrieves a specific 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}.au01.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": [
    ]
}

Remove PDF Template

Delete a PDF template by 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}.au01.mattr.global/v2/credentials/compact/pdf/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Compact Credential PDF Generation

Generate compact credential PDF

Creates a PDF based on provided compact credential payload as the encoded string and selected template

  • A PDF will fail to be generated if the credential being used can't be validated, or the credential itself 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

The credential payload

templateId
string non-empty

PDF Template identifier

payload
string [ 1 .. 1024 ] characters

Credential payload string

Responses

Request samples

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

Compact Credential Digital Pass Template Management

Create Apple Pass Template

Creates a custom Digital Pass template based on a composed .zip file in the template field. Other form values are required to establish the connection to your Apple Developer account.

Apple Pass template uses the official Apple Pass bundle structure

├── icon.png
├── icon@2x.png
├── logo.png
├── logo@2x.png
└── pass.json

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>
name
required
string [ 1 .. 1024 ] characters

Name of the template

fileName
required
string [ 1 .. 100 ] characters

File name for generated .pkpass bundles, should only include alphanumeric characters, '_', or '-', and ends with '.pkpass'.

teamIdentifier
required
string

Apple team identifier

passTypeIdentifier
required
string

Apple pass identifier

wwdr
required
string

Apple G1 or G4 WorldWide Developer Relations 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 signer certificate key

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.au01.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": {
    }
}

List Apple Pass Templates

Retrieves a list of all Digital Pass template available for use.

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}.au01.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 Apple Pass Template

Update an Apple Pass template based on the uploaded .zip archive data.

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

Digital Pass Template ID

Request Body schema: multipart/form-data
template
required
string <binary>
name
required
string [ 1 .. 1024 ] characters

Name of the template

fileName
required
string [ 1 .. 100 ] characters

File name for generated .pkpass bundles, should only include alphanumeric characters, '_', or '-', and ends with '.pkpass'.

teamIdentifier
required
string

Apple team identifier

passTypeIdentifier
required
string

Apple pass identifier

wwdr
required
string

Apple G1 or G4 WorldWide Developer Relations 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 signer certificate key

Responses

Request samples 

curl -i -X PUT \
  'https://{tenantName}.au01.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 Apple Pass Template

Retrieves a specific Apple Pass template

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>

Digital Pass Template ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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": {
    }
}

Remove Apple Pass Template

Delete a Apple Pass template by 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>

Digital Pass Template ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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": [
    ]
}

Google Pay Pass Template creation endpoint

Creates a custom Digital Pass template based on composed .zip file.

Google Pay Pass template must include the pass class and object definitions to be defined in a template.json file:

{
    "loyaltyClass": {
        ...
    },
    "loyaltyObject": {
        ...
    }
}

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>
name
required
string [ 1 .. 1024 ] characters

Name of the template

issuerId
required
string

Google Pay Pass signer issuer ID

serviceAccountClientEmail
required
string

Email address of the Google Cloud Platform service account for accessing the Google Pay Passes API and issue passes on-behalf of the pass issuer.

serviceAccountPrivateKey
required
string

Private key PEM of the Google Cloud Platform service account

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.au01.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": {
    }
}

List Google Pay Pass Template

Retrieves a list of all Digital Pass template available for use

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}.au01.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 Google Pay Pass Template

Update a Google Pay Pass template based on the uploaded .zip file data.

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

Digital Pass Template ID

Request Body schema: multipart/form-data
template
required
string <binary>
name
required
string [ 1 .. 1024 ] characters

Name of the template

issuerId
required
string

Google Pay Pass signer issuer ID

serviceAccountClientEmail
required
string

Email address of the Google Cloud Platform service account for accessing the Google Pay Passes API and issue passes on-behalf of the pass issuer.

serviceAccountPrivateKey
required
string

Private key PEM of the Google Cloud Platform service account

Responses

Request samples 

curl -i -X PUT \
  'https://{tenantName}.au01.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 Google Pay Pass Template

Retrieves a specific Digital Pass template by 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>

Digital Pass Template ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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": {
    }
}

Remove Google Pay Pass Template

Delete a Google Pay Pass template by 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>

Digital Pass Template ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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 Credential Digital Pass Generation

Generate Apple Pass

Creates an Apple Pass based on provided credential payload and selected template

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

Digital Pass Template identifier

payload
string

Credential payload string

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

Generate Google Pay Pass

Creates a Digital Pass based on provided credential payload and selected template

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

Digital Pass Template identifier

payload
string

Credential payload string

Responses

Request samples

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

Response samples

Content type
application/json
{}

Compact Credential Configuration

Create a Credential Configuration for a compact credential

Create a new Configuration for a compact credential that will be issued by your tenant.

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

Type for the credential, must be unique across credential configurations for the tenant, cannot contain whitespace, and must not be VerifiableCredential.

required
object

Claim mapping configuration to generate credential subject claims during issuance.

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

Indicates whether the credential is revocable.

claimSourceId
string <uuid>

Claim Source Id

object

Optional field that specifies how long after issuance credentials generated using this configuration will expire.

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 list of Credential Configurations for compact credentials

Returns a list of all Comapct Credential Configurations under 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}.au01.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 Credential Configuration

Retrieve an existing Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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 Credential Configuration

Update an already existing Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Update a Credential Configuration

type
required
string [ 1 .. 1024 ] characters

Type for the credential, must be unique across credential configurations for the tenant, cannot contain whitespace, and must not be VerifiableCredential.

required
object

Claim mapping configuration to generate credential subject claims during issuance.

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

Indicates whether the credential is revocable.

claimSourceId
string <uuid>

Claim Source Id

object

Optional field that specifies how long after issuance credentials generated using this configuration will expire.

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

Remove a Credential Configuration

Remove an already exising Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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": [
    ]
}

Semantic Compact Credentials

Sign a Compact Semantic Credential

Create a Compact Credential by providing a valid payload.

The iss contains the DID of the issuer, this must be a did:web using a P-256 key type available on the tenant.

The nbf (not before), exp (expiry) and iat (issued at) are all dates expressed as a Unix timestamp in seconds that control the validity period of the credential once it has been issued.

aud and sub are optional fields in the credential.

The vc object represents a W3C Verifiable Credential data model credential.

  • @context must be a resolvable schema
  • type is a single credential type
  • credentialSubject object contains all the claims about the subject.

Note: As compact semantic credentials are 'bearer credentials' including a subject identifier is not required.

A separate option can be provided to specify if the credential should be revocable, this is false by default.

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

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 credential

Verify a compact credential by sending the encoded payload and specifying options that could determine the resulting verification checks.

Standard checks performed on all verification requests:

  • Conformance of the string and encoded data, all Semantic Compact Credentials must be pre-fixed with CSS:/1
  • Decode the CWT structure and validate attributes on the Verifiable Credential
  • Resolve the remote context schema and validate claims can be dereferenced
  • Fetch the public key from the did.json of the issuer did:web and validate the proof signature

Optional parameter checks:

  • trustedIssuers if provided will compare the iss field against the array of trusted issuers and only return verified if found in the array.
  • assertNotBefore is a Unix timestamp provided in seconds, verify will fail if the current time is before the nbf value
  • assertNotAfter is a Unix timestamp provided in seconds, verify will fail if the current time is after the exp value
  • checkRevocation if the provided compact credential contains a revocation status list, this will be checked and verify will fail if the credential has been set to 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

a compact semantic credential encoded payload

trustedIssuers
Array of strings
assertNotBefore
boolean
Default: true
assertExpiry
boolean
Default: true
checkRevocation
boolean
Default: true

Responses

Request samples

Content type
application/json
application/json
multipart/form-data
{
  • "payload": "CSS:/1/2KCE3IQEJB5DCMSLN5KWKZABE2QFRMFEAF4CIZDJMQ5HOZLCHIYDGOJUFUYTENJNGIZTOLJVGIWTCMJQFZXGO4TPNMXGS33COZR2G2CAMNXW45DFPB2IC6BGNB2HI4DTHIXS653XO4XHOMZON5ZGOLZSGAYTQL3DOJSWIZLOORUWC3DTF53DCZDUPFYGLALUKZSXE2LGNFQWE3DFINZGKZDFNZ2GSYLMOFRXEZLEMVXHI2LBNRJXKYTKMVRXJILENZQW2ZLEJJXWQ3QH3BAFAW2MIRFQDICFCSNL5EIX4IISCEIFDJRFHCRRLBALWFYDLUVEKXHERNWHUDGJI3DDNNXSFWIRHUASBHGB2I7UHGPZMJEB3SMOFMBL3PABL5HUFSQLLGNE7YRKSAM3OAQN7F4LG365HL67BU",
  • "trustedIssuers": [
    ],
  • "assertNotBefore": true,
  • "assertExpiry": 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": {}
}

Remove credential metadata

Remove all stored credential metadata from a tenant for a specific credential using its ID. Note that only the metadata of revocable credentials or credentials issued through the OpenID4VCI flow is saved.

All credential metadata related to the issued credential is removed from the system and cannot be recovered. If the credential is revocable, it will be permanently revoked.

Authorizations:
bearerAuth
path Parameters
id
required
string

Credential ID

Responses

Request samples 

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

Response samples

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

Public revocation list discovery

Every revocable credential issued will reference a Revocation List, this is automatically created and held on the tenant for the Issuer.

The public revocation list endpoint can be obtained from the public revocation list discovery endpoint.

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}.au01.mattr.global/v2/credentials/compact-semantic/revocation-lists' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
[
  • {
    }
]

Public revocation list

The public endpoint that retrieves the revocation list that contains the revocation status of a number of credentials.

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

ID of the revocation list

Responses

Request samples 

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

Update revocation status

A credential can be revoked by setting isRevoked to true. The status can be set back to false to reactivate the credential.

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

Unqiue ID of the compact semantic credential

Request Body schema: application/json

Update revocation status

isRevoked
required
boolean

Responses

Request samples

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

Response samples

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

Retrieve revocation status

Retrieve the revocation status of a credential.

Authorizations:
bearerAuth
path Parameters
id
required
string

Unqiue ID of the compact semantic credential

Responses

Request samples 

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

Response samples

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

Generate a QR Code

Generate a QR Code to represent a Compact Semantic Credential from the base32 encoded string provided as the payload and an optional width.

  • The maximum length of the payload is 3391 characters.

The width of the output QR code can be specified using the optional width parameter.

  • The maximum size of the width is 1000px. If not provided the QR code library will generate a QR code with optimised width based on the size of the payload in the request.

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 payload of the encoded compact credential

width
number

Width in pixels of the output png image

Responses

Request samples

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

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

Semantic Compact Credential Configuration

Create a Credential Configuration for a compact semantic credential

Create a new Configuration for a compact semantic credential that will be issued by your tenant.

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

Type for the credential, must be unique across credential configurations for the tenant, cannot contain whitespace, and must not be VerifiableCredential.

required
object

Claim mapping configuration to generate credential subject claims during issuance.

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

Indicates whether the credential is revocable.

claimSourceId
string <uuid>

Claim Source Id

object

Optional field that specifies how long after issuance credentials generated using this configuration will expire.

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 list of Credential Configurations for compact semantic credentials

Returns a list of all Comapct Semantic Credential Configurations under 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}.au01.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 Credential Configuration

Retrieve an existing Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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 Credential Configuration

Update an already existing Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Update a Credential Configuration

type
required
string [ 1 .. 1024 ] characters

Type for the credential, must be unique across credential configurations for the tenant, cannot contain whitespace, and must not be VerifiableCredential.

required
object

Claim mapping configuration to generate credential subject claims during issuance.

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

Indicates whether the credential is revocable.

claimSourceId
string <uuid>

Claim Source Id

object

Optional field that specifies how long after issuance credentials generated using this configuration will expire.

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

Remove a Credential Configuration

Remove an already exising Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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": [
    ]
}

Semantic Compact Credential PDF Template Management

Create PDF Template

Creates a custom PDF template based on composed .zip archive data. Each .zip archive should include:

  • A PDF template called template.pdf
  • Font files in a font directory
  • A JSON file called config.json describing fields, its validation rules and fonts.

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

List PDF Templates

Retrieves a list of all Compact Semanitc Credential PDF templates available for use.

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}.au01.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 PDF Template

Update a PDF template based on uploaded .zip archive data.

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}.au01.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 PDF Template

Retrieves a specific 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}.au01.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": [
    ]
}

Remove PDF Template

Delete a PDF template by 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}.au01.mattr.global/v2/credentials/compact-semantic/pdf/templates/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Semantic Compact Credential PDF Generation

Generate compact semantic credential PDF

Creates a PDF based on provided compact semantic credential payload as the encoded string and selected template

  • A PDF will fail to be generated if the credential being used can't be validated, or the credential itself 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

PDF Template identifier

payload
string [ 1 .. 1024 ] characters

Credential payload string

Responses

Request samples

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

Semantic Compact Credential Digital Pass Template Management

Create Apple Pass Template

Creates a custom Digital Pass template based on a composed .zip file in the template field. Other form values are required to establish the connection to your Apple Developer account.

Apple Pass template uses the official Apple Pass bundle structure

├── icon.png
├── icon@2x.png
├── logo.png
├── logo@2x.png
└── pass.json

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>
name
required
string [ 1 .. 1024 ] characters

Name of the template

fileName
required
string [ 1 .. 100 ] characters

File name for generated .pkpass bundles, should only include alphanumeric characters, '_', or '-', and ends with '.pkpass'.

teamIdentifier
required
string

Apple team identifier

passTypeIdentifier
required
string

Apple pass identifier

wwdr
required
string

Apple G1 or G4 WorldWide Developer Relations 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 signer certificate key

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.au01.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": {
    }
}

List Apple Pass Templates

Retrieves a list of all Digital Pass template available for use.

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}.au01.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 Apple Pass Template

Update an Apple Pass template based on the uploaded .zip archive data.

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

Digital Pass Template ID

Request Body schema: multipart/form-data
template
required
string <binary>
name
required
string [ 1 .. 1024 ] characters

Name of the template

fileName
required
string [ 1 .. 100 ] characters

File name for generated .pkpass bundles, should only include alphanumeric characters, '_', or '-', and ends with '.pkpass'.

teamIdentifier
required
string

Apple team identifier

passTypeIdentifier
required
string

Apple pass identifier

wwdr
required
string

Apple G1 or G4 WorldWide Developer Relations 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 signer certificate key

Responses

Request samples 

curl -i -X PUT \
  'https://{tenantName}.au01.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 Apple Pass Template

Retrieves a specific Apple Pass template

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>

Digital Pass Template ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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": {
    }
}

Remove Apple Pass Template

Delete a Apple Pass template by 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>

Digital Pass Template ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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": [
    ]
}

Google Pay Pass Template creation endpoint

Creates a custom Digital Pass template based on composed .zip file.

Google Pay Pass template must include the pass class and object definitions to be defined in a template.json file:

{
    "loyaltyClass": {
        ...
    },
    "loyaltyObject": {
        ...
    }
}

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>
name
required
string [ 1 .. 1024 ] characters

Name of the template

issuerId
required
string

Google Pay Pass signer issuer ID

serviceAccountClientEmail
required
string

Email address of the Google Cloud Platform service account for accessing the Google Pay Passes API and issue passes on-behalf of the pass issuer.

serviceAccountPrivateKey
required
string

Private key PEM of the Google Cloud Platform service account

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.au01.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": {
    }
}

List Google Pay Pass Template

Retrieves a list of all Digital Pass template available for use

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}.au01.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 Google Pay Pass Template

Update a Google Pay Pass template based on the uploaded .zip file data.

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

Digital Pass Template ID

Request Body schema: multipart/form-data
template
required
string <binary>
name
required
string [ 1 .. 1024 ] characters

Name of the template

issuerId
required
string

Google Pay Pass signer issuer ID

serviceAccountClientEmail
required
string

Email address of the Google Cloud Platform service account for accessing the Google Pay Passes API and issue passes on-behalf of the pass issuer.

serviceAccountPrivateKey
required
string

Private key PEM of the Google Cloud Platform service account

Responses

Request samples 

curl -i -X PUT \
  'https://{tenantName}.au01.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 Google Pay Pass Template

Retrieves a specific Digital Pass template by 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>

Digital Pass Template ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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": {
    }
}

Remove Google Pay 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>

Digital Pass Template ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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": [
    ]
}

Semantic Compact Credential Digital Pass Generation

Generate Apple Pass

Creates an Apple Pass based on provided credential payload and selected template

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

Digital Pass Template identifier

payload
string

Credential payload string

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

Generate Google Pay Pass

Creates a Digital Pass based on provided credential payload and selected template

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

Digital Pass Template identifier

payload
string

Credential payload string

Responses

Request samples

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

Response samples

Content type
application/json
{}

Semantic Compact Credential Configuration

Create a Credential Configuration for a compact semantic credential

Create a new Configuration for a compact semantic credential that will be issued by your tenant.

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

Type for the credential, must be unique across credential configurations for the tenant, cannot contain whitespace, and must not be VerifiableCredential.

required
object

Claim mapping configuration to generate credential subject claims during issuance.

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

Indicates whether the credential is revocable.

claimSourceId
string <uuid>

Claim Source Id

object

Optional field that specifies how long after issuance credentials generated using this configuration will expire.

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 list of Credential Configurations for compact semantic credentials

Returns a list of all Comapct Semantic Credential Configurations under 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}.au01.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 Credential Configuration

Retrieve an existing Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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 Credential Configuration

Update an already existing Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Update a Credential Configuration

type
required
string [ 1 .. 1024 ] characters

Type for the credential, must be unique across credential configurations for the tenant, cannot contain whitespace, and must not be VerifiableCredential.

required
object

Claim mapping configuration to generate credential subject claims during issuance.

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

Indicates whether the credential is revocable.

claimSourceId
string <uuid>

Claim Source Id

object

Optional field that specifies how long after issuance credentials generated using this configuration will expire.

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

Remove a Credential Configuration

Remove an already exising Credential Configuration by providing a credential 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>

Credential Configuration ID

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

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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": [
    ]
}

Claim Source

Create a claim source

Create a new claim source for your tenant. When issuing a new credential, MATTR VII will query the created claim source. Any returned claims can be mapped into the credential being issued. When you create a claim source, you must configure how MATTR VII will authenticate when making the query. This can be either a shared secret (x-api-key header) or a bearer token (OAuth 2.0 client credentials).

Analytics 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

Claim source description

url
required
string

Base url for the claims source. 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.

requestMethod
string

The method MATTR VII will use to query the claims source. Both GET and POST are supported, with GET used by default. When using POST as a request method, all requestParameters must be included in the request body in JSON format.

Enum: "GET" "POST"
required
object

Request parameters to be included in the request to your server. Must supply mapFrom and/or defaultValue.

required
API Key (object) or OAuth Client Credentials (object)

Access control configuration for claim source request.

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": "Claim source that accepts 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": "Claim source that accepts x-api-key header",
  • "url": "https://example.com/api/data",
  • "authorization": {
    },
  • "requestParameters": {
    }
}

Retrieve list of claim sources

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

Analytics 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}.au01.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 claim source

Retrieve an existing claim source by providing its claimSourceID.

Analytics event

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

Claim Source ID

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

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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 claim source

Update an existing claim source by providing its claimSourceID.

Analytics event

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

Claim Source ID

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

The updated claim source payload

name
required
string

Claim source description

url
required
string

Base url for the claims source. 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.

requestMethod
string

The method MATTR VII will use to query the claims source. Both GET and POST are supported, with GET used by default. When using POST as a request method, all requestParameters must be included in the request body in JSON format.

Enum: "GET" "POST"
required
object

Request parameters to be included in the request to your server. Must supply mapFrom and/or defaultValue.

required
API Key (object) or OAuth Client Credentials (object)

Access control configuration for claim source request.

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 claim source

Delete an existing claim source by providing its claimSourceID.

Analytics event

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

Claim Source ID

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

Responses

Request samples 

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

Response samples

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

Authentication Provider

Create an Authentication Provider

Create a new Authentication Provider for this tenant.

IMPORTANT: For now, only one authentication provider can be configured. In the future we will support multiple Authentication Providers and relax this restriction.

The /.well-known/openid-configuration endpoint of the OpenID Provider needs to 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 OpenID Provider's well-known endpoint. 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"]

OIDC scopes to use during authentication to authorize access to a user's details. Each scope returns a set of user attributes, which are called claims.

clientId
required
string

Client ID configured in the OpenID Provider

clientSecret
required
string

Client secret configured in the OpenID Provider

tokenEndpointAuthMethod
string
Default: "client_secret_basic"

Authentication method for the OpenID Provider's token endpoint

Enum: "client_secret_basic" "client_secret_post"
object

Additional parameters that will be included in the request to the OpenID Provider. Keys must be strings. Values of top level object keys must stringify to less than 1000 characters each

forwardedRequestParameters
Array of strings

Additional parameters that can be provided by the client to be forwarded to the OpenID Provider. The forwarded parameter values are limited to under 1000 characters each

claimsToPersist
Array of strings
Default: []

List of claims to sync from the OpenID Provider against the corresponding MATTR VII user in persistent storage

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": [
    ],
  • "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": "https://example-university.au.auth0.com",
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "***********************************************************6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": [
    ],
  • "claimsToPersist": [
    ]
}

Retrieve list of Authentication Providers

Returns a list of all Authentication Providers.

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}.au01.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 Authentication Provider by providing an 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}.au01.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": "https://example-university.au.auth0.com",
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "***********************************************************6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": [
    ],
  • "claimsToPersist": [
    ]
}

Update an Authentication Provider

Update an Authentication Provider.

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"]

OIDC scopes to use during authentication to authorize access to a user's details. Each scope returns a set of user attributes, which are called claims.

clientId
required
string

Client ID configured in the OpenID Provider

clientSecret
string

Client secret configured in the OpenID Provider

tokenEndpointAuthMethod
string
Default: "client_secret_basic"

Authentication method for the OpenID Provider's token endpoint

Enum: "client_secret_basic" "client_secret_post"
object

Additional parameters that will be included in the request to the OpenID Provider. Keys must be strings. Values of top level object keys must stringify to less than 1000 characters each

forwardedRequestParameters
Array of strings

Additional parameters that can be provided by the client to be forwarded to the OpenID Provider. The forwarded parameter values are limited to under 1000 characters each

claimsToPersist
Array of strings
Default: []

List of claims to sync from the OpenID Provider against the corresponding MATTR VII user in persistent storage

Responses

Request samples

Content type
application/json
{
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "QNwfa4Yi4Im9zy1u_15n7SzWKt-9G5cdH0r1bONRpUPfN-UIRaaXv_90z8V6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": [
    ],
  • "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": "https://example-university.au.auth0.com",
  • "scope": [
    ],
  • "clientId": "vJ0SCKchr4XjC0xHNE8DkH6Pmlg2lkCN",
  • "clientSecret": "***********************************************************6-OjH",
  • "tokenEndpointAuthMethod": "client_secret_post",
  • "staticRequestParameters": {
    },
  • "forwardedRequestParameters": [
    ],
  • "claimsToPersist": [
    ]
}

Remove an Authentication Provider

Removes an Authentication Provider by providing an 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}.au01.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": [
    ]
}

OpenID Configuration

Update OpenID Configuration

Update an already existing OpenID Configuration for your tenant.

IMPORTANT: Only one OpenID Configuration can be configured per tenant.

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 OpenID Configuration payload

object (OpenIdConfigurationInteractionHookRequest)

Interaction Hook configuration.

Responses

Request samples

Content type
application/json
{}

Response samples

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

Retrieve OpenID Configuration

Retrieve an existing OpenID Configuration for 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}.au01.mattr.global/core/v1/openid/configuration' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

User

Search Users

Search users that match the provided criteria for this tenant.

Authorizations:
bearerAuth
Request Body schema: application/json

The search criteria

claims
object

Sample claims to be used on matching the users. Nestsed objects are supported. Text values must be an exact match.

object

Authentication Provider filter. All properties are optional.

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 list of Users

Returns a list of all Users.

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}.au01.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 a User by providing an ID.

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

Update a User.

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

Responses

Request samples

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

Response samples

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

User Credential

Retrieve list of User Credentials

Returns a list of all Credential references for a User.

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}.au01.mattr.global/core/v1/users/:userId/credentials' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

OpenID 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}.au01.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}.au01.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

This endpoint is used to issue a verifiable credential to a subject. 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

The format of the credential.

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 OpenID credential issuance offer URI

This endpoint is used to create an OpenID credential issuance 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

A list of valid credential IDs created from the credential configuration endpoint.

object

JSON object containing valid request parameters.

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"
}

Well Known OpenId4VCI credential issuer metadata

The standard OpenID4VCI Connect Well Known credential issuer metadata 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 OpenID Connect 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"
}

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

Create a new OIDC Credential Verifier for this tenant.

The verifierDid is the Verifier DID that will be used to securely send the Credential to.

The presentationTemplateId references the Presentation Template that defines what Credential is being requested for presentation.

Claim mappings are used to map JSON-LD terms used in a Credential to OpenID Connect terms used by clients.

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

The Verifier DID

presentationTemplateId
required
string <uuid>

Presentation Template ID used to request certain credentials

required
Array of objects

Map OpenID Connect terms to JSON-LD terms

includePresentation
boolean

Include presentation object in the id_token

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 list of OIDC Verifiers

Returns a list of all OIDC Verifiers in 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}.au01.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

Retrieve an OIDC Verifier by providing a Verifier 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}.au01.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

Update an OIDC Credential Verifier.

The verifierDid is the Verifier DID that will be used to securely send the Credential to.

The presentationTemplateId references the Presentation Template that defines what Credential is being requested for presentation.

Claim mappings are used to map JSON-LD terms used in a Credential to OpenID Connect terms used by clients. The jsonLdContext is used to define the JSON-LD schema for the JSON-LD terms.

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

The Verifier DID

presentationTemplateId
required
string <uuid>

Presentation Template ID used to request certain credentials

required
Array of objects

Map OpenID Connect terms to JSON-LD terms

includePresentation
boolean

Include presentation object in the id_token

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
}

Remove an OIDC Verifier

Removes an OIDC Verifier by providing a Verifier 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}.au01.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

Create a Client

Relying party clients are required to be created in the system for Authorization and VC Verify flows that are enabled through OIDC.

The Create Client endpoint accepts OpenID Connect standard registration parameters.

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

Meaningful name for this Client

redirectUris
required
Array of strings <uri>

Redirection URI to which the response will be sent

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 list of Clients

Returns a list of all OIDC Verifier Clients in 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}.au01.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 a Client

Retrieve an OIDC Verifier Client by providing a Client 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>

Verifier ID

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

Client ID

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

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.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 a Client

Update an OIDC Verifier Client.

The Client endpoint accepts OpenID Connect standard registration parameters.

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_UPDATE_START
  • OIDC_VERIFIER_CLIENT_UPDATE_SUCCESS
  • OIDC_VERIFIER_CLIENT_UPDATE_FAIL
Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

Verifier ID

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

Client ID

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

Update a client

name
required
string

Meaningful name for this Client

redirectUris
required
Array of strings <uri>

Redirection URI to which the response will be sent

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"
}

Remove a Client

Removes an OIDC Verifier Client by providing a Client 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>

Verifier ID

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

Client ID

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

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.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": [
    ]
}

DCC Document Signers

Create a Document Signer

Creates a document signer to represent an entity that is authorised to sign a Digital Covid Certificate payload. The document signer is initially created as a self-signed certificate that can be updated after creation to be associated to a Country Signing Certification Authority (CSCA).

The self-signed certificate can be used to sign a DCC for testing purposes without the associated to a CSCA. However, to fit within the trust framework outlined for the EUDCC, the document signer should be chained to a CSCA. This can be achieved by providing the publicKey and/or certificatePem to a CSCA to chain together and provide back a certificatePem that can then be updated against the created documentSigner.

There must be at least one document signer created to allow for a DCC to be signed through the sign API endpoint.

Authorizations:
bearerAuth

Responses

Request samples 

curl -i -X POST \
  'https://{tenantName}.au01.mattr.global/ext/dcc/v1/documentsigners' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
No sample

Retrieve list of Document Signers

Retrieves a list of document signers which have been added through the DCC extension and are available for use when signing a Digital Covid Certificate (DCC) via the sign API endpoint.

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}.au01.mattr.global/ext/dcc/v1/documentsigners?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Retrieve a Document Signer by ID

Get a document signer by id

Authorizations:
bearerAuth
path Parameters
id
required
string

Document Signer ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.mattr.global/ext/dcc/v1/documentsigners/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "certificateKid": "a2c5ab3515c03fa4",
  • "certificateFingeprint": "a2c5ab3515c03fa45b7d005dceebfcd4f1e83532aac31101ee3c6218d8ebff10",
  • "certificatePem": "-----BEGIN CERTIFICATE----- MIIBdjCCAR2gAwIBAgIBATAKBggqhkjOPQQDAjAgMR4wCQYDVQQGEwJOWjARBgNV BAMeCgBNAGEAdAB0AHIwHhcNMjEwNzExMjEzMDU3WhcNMjIwNzExMjEzMDU3WjAg MR4wCQYDVQQGEwJOWjARBgNVBAMeCgBNAGEAdAB0AHIwWTATBgcqhkjOPQIBBggq hkjOPQMBBwNCAAQtyjLgdBIkwZbwQjnJ1J+1md176GwiWESb0hAc3O0ulaSIYRQk HrtZk0/Wmxj/iiU/QAdQ0MxHgTw3tdceZ3gIo0gwRjASBgNVHRMBAf8ECDAGAQH/ AgEDMDAGA1UdJQQpMCcGCysGAQQBjjePZQEBBgsrBgEEAY43j2UBAgYLKwYBBAGO N49lAQMwCgYIKoZIzj0EAwIDRwAwRAIhAI5zqK+cFUgJiVc+kAKNRuBvrjkRRq9C fs+oaGyHWh5AAh8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA -----END CERTIFICATE-----",
  • "certificateData": {
    },
  • "publicKey": {
    }
}

Delete a Document Signer by ID

Remove a document signer by id

Authorizations:
bearerAuth
path Parameters
id
required
string

Document Signer ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.mattr.global/ext/dcc/v1/documentsigners/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
No sample

Update a Document Signer

Update a document signer by id with a new or replacement certificatePem that represents the trusted chain between the document signer and root certificate of the associated CSCA.

Authorizations:
bearerAuth
path Parameters
id
required
string

Document Signer ID

Request Body schema: application/json
certificatePem
string

PEM encoded X.509 certificate

Responses

Request samples

Content type
application/json
{
  • "certificatePem": "-----BEGIN CERTIFICATE-----\\r\\nMIIBdjCCAR2gAwIBAgIBATAKBggqhkjOPQQDAjAgMR4wCQYDVQQGEwJOWjARBgNV\\r\\nBAMeCgBNAGEAdAB0AHIwHhcNMjEwOTE2MDMyNDM4WhcNMjMwOTE2MDMyNDM4WjAg\\r\\nMR4wCQYDVQQGEwJOWjARBgNVBAMeCgBNAGEAdAB0AHIwWTATBgcqhkjOPQIBBggq\\r\\nhkjOPQMBBwNCAAQJJy6qRSK7P7m15b+zckhLGCfkrh4VcldVP44q3SDAxhWKxETa\\r\\n9Gw5JDjQi8AM8LPbAR7/wM4pS9UkQvuKbkM0o0gwRjASBgNVHRMBAf8ECDAGAQH/\\r\\nAgEDMDAGA1UdJQQpMCcGCysGAQQBjjePZQECBgsrBgEEAY43j2UBAQYLKwYBBAGO\\r\\nN49lAQMwCgYIKoZIzj0EAwIDRwAwRAIgHs8ZpdsdcQSAjN5sN+4JR0fCUilD+N25\\r\\nC1w+VYiRiDICIHxfjxu99xhQe74cY9OdS19k1iwM99g8ivWuNPHZvoVv\\r\\n-----END CERTIFICATE-----\\r\\n"
}

Response samples

Content type
application/json
No sample

DCC Trusted Document Signers

Import an new Trusted Document Signer

Creates a trusted document signer from the provided PEM certificate that has been issued by a CSCA (or similar authority) to represent an entity that is authorised to sign a Digital Covid Certificate payload.

The certificatePem, must be an encoded X.509 certificate for it to be accepted.

For a DCC to be considered verified through the verify endpoint, the document signer that issued the DCC needs to be registered as a trusted issuer.

A certificate that has been utilised by a sign operation will automatically be imported as a trust document signer.

Authorizations:
bearerAuth
Request Body schema: application/json
certificatePem
required
string

PEM encoded X.509 certificate

public
required
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "certificatePem": "-----BEGIN CERTIFICATE-----\\r\\nMIIBdjCCAR2gAwIBAgIBATAKBggqhkjOPQQDAjAgMR4wCQYDVQQGEwJOWjARBgNV\\r\\nBAMeCgBNAGEAdAB0AHIwHhcNMjEwOTE2MDMyNDM4WhcNMjMwOTE2MDMyNDM4WjAg\\r\\nMR4wCQYDVQQGEwJOWjARBgNVBAMeCgBNAGEAdAB0AHIwWTATBgcqhkjOPQIBBggq\\r\\nhkjOPQMBBwNCAAQJJy6qRSK7P7m15b+zckhLGCfkrh4VcldVP44q3SDAxhWKxETa\\r\\n9Gw5JDjQi8AM8LPbAR7/wM4pS9UkQvuKbkM0o0gwRjASBgNVHRMBAf8ECDAGAQH/\\r\\nAgEDMDAGA1UdJQQpMCcGCysGAQQBjjePZQECBgsrBgEEAY43j2UBAQYLKwYBBAGO\\r\\nN49lAQMwCgYIKoZIzj0EAwIDRwAwRAIgHs8ZpdsdcQSAjN5sN+4JR0fCUilD+N25\\r\\nC1w+VYiRiDICIHxfjxu99xhQe74cY9OdS19k1iwM99g8ivWuNPHZvoVv\\r\\n-----END CERTIFICATE-----\\r\\n"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "certificateKid": "a2c5ab3515c03fa4",
  • "certificateFingeprint": "a2c5ab3515c03fa45b7d005dceebfcd4f1e83532aac31101ee3c6218d8ebff10",
  • "certificatePem": "-----BEGIN CERTIFICATE----- MIIBdjCCAR2gAwIBAgIBATAKBggqhkjOPQQDAjAgMR4wCQYDVQQGEwJOWjARBgNV BAMeCgBNAGEAdAB0AHIwHhcNMjEwNzExMjEzMDU3WhcNMjIwNzExMjEzMDU3WjAg MR4wCQYDVQQGEwJOWjARBgNVBAMeCgBNAGEAdAB0AHIwWTATBgcqhkjOPQIBBggq hkjOPQMBBwNCAAQtyjLgdBIkwZbwQjnJ1J+1md176GwiWESb0hAc3O0ulaSIYRQk HrtZk0/Wmxj/iiU/QAdQ0MxHgTw3tdceZ3gIo0gwRjASBgNVHRMBAf8ECDAGAQH/ AgEDMDAGA1UdJQQpMCcGCysGAQQBjjePZQEBBgsrBgEEAY43j2UBAgYLKwYBBAGO N49lAQMwCgYIKoZIzj0EAwIDRwAwRAIhAI5zqK+cFUgJiVc+kAKNRuBvrjkRRq9C fs+oaGyHWh5AAh8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA-----END CERTIFICATE-----",
  • "certificateData": {
    }
}

Retrieve list of Trusted Document Signers

Retrieves a list of trusted document signers which have been added through the DCC extension and are available and trusted as valid certificate signers when verifying a Digital Covid Certificate (DCC) via the verify API endpoint.

Authorizations:
bearerAuth
query Parameters
kid
string

Filter by certificate kid

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}.au01.mattr.global/ext/dcc/v1/trusteddocumentsigners?kid=string&limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Get a Trusted Document Signer by ID

Get a trusted document signer by id

Authorizations:
bearerAuth
path Parameters
id
required
string

Trusted Document Signer ID

Responses

Request samples 

curl -i -X GET \
  'https://{tenantName}.au01.mattr.global/ext/dcc/v1/trusteddocumentsigners/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "certificateKid": "a2c5ab3515c03fa4",
  • "certificateFingeprint": "a2c5ab3515c03fa45b7d005dceebfcd4f1e83532aac31101ee3c6218d8ebff10",
  • "certificatePem": "-----BEGIN CERTIFICATE----- MIIBdjCCAR2gAwIBAgIBATAKBggqhkjOPQQDAjAgMR4wCQYDVQQGEwJOWjARBgNV BAMeCgBNAGEAdAB0AHIwHhcNMjEwNzExMjEzMDU3WhcNMjIwNzExMjEzMDU3WjAg MR4wCQYDVQQGEwJOWjARBgNVBAMeCgBNAGEAdAB0AHIwWTATBgcqhkjOPQIBBggq hkjOPQMBBwNCAAQtyjLgdBIkwZbwQjnJ1J+1md176GwiWESb0hAc3O0ulaSIYRQk HrtZk0/Wmxj/iiU/QAdQ0MxHgTw3tdceZ3gIo0gwRjASBgNVHRMBAf8ECDAGAQH/ AgEDMDAGA1UdJQQpMCcGCysGAQQBjjePZQEBBgsrBgEEAY43j2UBAgYLKwYBBAGO N49lAQMwCgYIKoZIzj0EAwIDRwAwRAIhAI5zqK+cFUgJiVc+kAKNRuBvrjkRRq9C fs+oaGyHWh5AAh8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA-----END CERTIFICATE-----",
  • "certificateData": {
    }
}

Delete a Trusted Document Signer by ID

Delete a trusted document signer by id

Authorizations:
bearerAuth
path Parameters
id
required
string

Trusted Document Signer ID

Responses

Request samples 

curl -i -X DELETE \
  'https://{tenantName}.au01.mattr.global/ext/dcc/v1/trusteddocumentsigners/:id' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Update a Trusted Document Signer

Update a trusted document signer's public property to indicate this document signers public key can be included in the list of document signers returned via a dccgateway endpoint, for external relying parties/verifiers to utilise.

Please note that this method may not be available on your tenant as it is dependent on MATTR VII environment configuration.

Authorizations:
bearerAuth
path Parameters
id
required
string

Trusted Document Signer ID

Request Body schema: application/json
public
boolean

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "certificateKid": "a2c5ab3515c03fa4",
  • "certificateFingeprint": "a2c5ab3515c03fa45b7d005dceebfcd4f1e83532aac31101ee3c6218d8ebff10",
  • "certificatePem": "-----BEGIN CERTIFICATE----- MIIBdjCCAR2gAwIBAgIBATAKBggqhkjOPQQDAjAgMR4wCQYDVQQGEwJOWjARBgNV BAMeCgBNAGEAdAB0AHIwHhcNMjEwNzExMjEzMDU3WhcNMjIwNzExMjEzMDU3WjAg MR4wCQYDVQQGEwJOWjARBgNVBAMeCgBNAGEAdAB0AHIwWTATBgcqhkjOPQIBBggq hkjOPQMBBwNCAAQtyjLgdBIkwZbwQjnJ1J+1md176GwiWESb0hAc3O0ulaSIYRQk HrtZk0/Wmxj/iiU/QAdQ0MxHgTw3tdceZ3gIo0gwRjASBgNVHRMBAf8ECDAGAQH/ AgEDMDAGA1UdJQQpMCcGCysGAQQBjjePZQEBBgsrBgEEAY43j2UBAgYLKwYBBAGO N49lAQMwCgYIKoZIzj0EAwIDRwAwRAIhAI5zqK+cFUgJiVc+kAKNRuBvrjkRRq9C fs+oaGyHWh5AAh8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA-----END CERTIFICATE-----",
  • "certificateData": {
    }
}

DCC Sign

Sign a Digital Covid Certificate

Creates a signed DCC (Digital Covid Certificate) using either the specified document signer or selected default (if one isn't provided in the request payload).

If supplied, documentSignerId must be a valid UUID for a document signer set up under the documentsigners endpoint.

An expiry value can also be supplied specify to the expiration of the signed payload. If not provided, the sign operation will default the expiry to be one year from the current date - as recommended under the specification.

The payload should conform with the JSON schema outlined in the EUDCC specification.

The payload.[v|r|t] should be an array with only one item, and only one of the field [v|r|t] is supported at the same time, it depends on the type of certificate.

The payload.[v|r|t][0].ci value will be automatically generated. If supplied an 400 Bad Request response will be returned.

The metadata is an optional map of key value pairs (string, string).

Validation will be performed as part of this operation to ensure the payload is valid against the schema specified under the payload.ver in the request.

Analytic events

  • DCC_SIGN_START
  • DCC_SIGN_SUCCESS
  • DCC_SIGN_FAIL
Authorizations:
bearerAuth
Request Body schema:
application/json
application/json
application/xml

DCC payload to sign

expiry
string <date-time>

Note - this field is optional and if not supplied MATTR VII will use the default expiry which is 1 year as recommended by the DCC specification

documentSignerId
string <uuid>

Note - this field is optional and if not supplied, MATTR VII will attempt to automatically decide which document signer to use.

required
object (DigitalCovidCertificateWithoutCertificateId)
object

Note - this field is an optional (string, string) map of metadata

Responses

Request samples

Content type
application/json
application/json
application/xml
Example
VaccineCertificate
VaccineCertificate
TestCertificate
RecoveryCertificate
{
  • "payload": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "payload": "HC1:6BFT70I90T9WTWGSLKC 4W59BFIZO1XM4$FOFBBT30FS0QE8$R8$X8X$9W*0QE8VE73+K5.J*70X+9D97TK0F90$PC5$CUZCY$5Y$5TPCBEC7ZKW.CWOCW3ELPCG/DWOC/0A JC0/DKI949DMPCG/DOUC11A.+9GVC*JC1A6IA74W5Y96TF6KECTHG4KCD3DX47B46IL6646H*6Z/E5JD%96IA7B46646VX6Q$D.UDRYA 96NF6L/5SW6Y57B$D% D3IA4W5646946846.96XJC$+D3KC.SCXJCCWENF6OF63W5KF60A6WJCT3EX+9%JCUQE8H8YNAZ6AM347%EKWEMEDWJC0FDU56:KEPH7M/ESDD746IG77TA$96T476:6/Q6M*8CR63Y8R46WX8F46VL6/G8SF6DR64S8+96-9A268658EDUXINC5QUE7WYBZCJ/OIYJ7-+BH03L%4/.LY017XRHCUX4DW1N/UK72LO/5S8FEUP*OFT U-/9JUI-+FMRN+YH9CC/01HZDUMS81"
}

DCC Verify

Verify a Digital Covid Certificate

Verify a Digital Covid Certificate (DCC) from the provided base45 encoded string provided to the payload of the request.

Analytic events

  • DCC_VERIFY_START
  • DCC_VERIFY_SUCCESS
  • DCC_VERIFY_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The signed DCC represented as base45 encoded string

payload
required
string

Base45 encoded DCC

Responses

Request samples

Content type
application/json
{
  • "payload": "HC1:6BFT70I90T9WTWGSLKC 4W59BFIZO1XM4$FOFBBT30FS0QE8$R8$X8X$9W*0QE8VE73+K5.J*70X+9D97TK0F90$PC5$CUZCY$5Y$5TPCBEC7ZKW.CWOCW3ELPCG/DWOC/0A JC0/DKI949DMPCG/DOUC11A.+9GVC*JC1A6IA74W5Y96TF6KECTHG4KCD3DX47B46IL6646H*6Z/E5JD%96IA7B46646VX6Q$D.UDRYA 96NF6L/5SW6Y57B$D% D3IA4W5646946846.96XJC$+D3KC.SCXJCCWENF6OF63W5KF60A6WJCT3EX+9%JCUQE8H8YNAZ6AM347%EKWEMEDWJC0FDU56:KEPH7M/ESDD746IG77TA$96T476:6/Q6M*8CR63Y8R46WX8F46VL6/G8SF6DR64S8+96-9A268658EDUXINC5QUE7WYBZCJ/OIYJ7-+BH03L%4/.LY017XRHCUX4DW1N/UK72LO/5S8FEUP*OFT U-/9JUI-+FMRN+YH9CC/01HZDUMS81"
}

Response samples

Content type
application/json
Example
VaccineCertificate
VaccineCertificate
TestCertificate
RecoveryCertificate
FailedVerifyCertificate
{
  • "verified": true,
  • "metadata": {
    },
  • "payload": {
    }
}

DCC Format Extensions

Generate the QR to represent a Digital Covid Certificate

Generate a QR code to represent a digital covid certificate from the base45 encoded string provided as the payload.

Analytic events

  • DCC_FORMAT_QRCODE_START
  • DCC_FORMAT_QRCODE_SUCCESS
  • DCC_FORMAT_QRCODE_FAIL
Authorizations:
bearerAuth
Request Body schema: application/json

The signed DCC represented as a base45 encoded string.

payload
required
string

Base45 encoded DCC

Responses

Request samples

Content type
application/json
{
  • "payload": "HC1:6BFTW2EM75VOP10KHHTSHFTM7*2X%J9RF4*3/Q8 M36 9E2LP-Q%F3J-RVYK ED9W41PD/I5LPK0$51+72V0O22DR8A25A-1JAHKQSU/D$:7A:LD2F T3+ 3*%U++4*62B:9HW7$SR-.06S1:JTRM4:QBD3Q*K5%ASV9EPC9NPROFJCLL6:JN8H794SCLOVD-4HX*UPNRK 7BTM5 L45G+BOMSQT/TP8HHY2/V99E4Z-CE.P/X5%TQUS8DL8Q6QXYJJGC.*MU-6+HAQ6LFYA6GGM52KYI7+3:QMOE0X0TH:L4QRK8VU0MA3024J.5320RCT7AAAH-G9H31:OMC08K4NQO/01L97V:20MCBFQN01FESG-02 JDO1 5DPBE7AQF 5I3CBD2J/K41362J ON91SHEU+H0A.4-9N4NGXH1:JB.CNA7DUE9-ZJBS9.00/KQMS0E91T49S:3N$GLF8584OFP%U9Q%SCD8DLI/18Q2O0R54T7$BV0+UPBU5/D1.HUV6LPD8/4%KK- S.HP6$8J5MDVLJ0Q3:EQLA8NF46FJ-FKYFP0GT+4*GOC R:876LM%*34RV8L0D0672"
}