Platform Core API (v2.0.0)

Download OpenAPI specification:Download

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",
  • "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:
Request Body schema:

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

Response samples

Content type
application/json
{
  • "name": "Example Corp",
  • "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:

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

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

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:
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:
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
{
  • "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:
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:
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:
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:
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:
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
{
  • "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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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
{
  • "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:
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": [
    ],
  • "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:
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:
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": [
    ],
  • "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:
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": [
    ],
  • "disabled": false
}

Remove a webhook

Removes a specific webhook from this tenant.

Analytic events

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

Webhook ID

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

Responses

Request samples

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

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

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

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:
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": 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:
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
{
  • "options": {
    },
  • "data": {}
}

Response samples

Content type
application/json
Example
{
  • "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:
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:
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:
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:
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:
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:
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:
Request Body schema:
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