MATTR VII API (v2.3.0)

Download OpenAPI specification:Download

Introduction

The MATTR VII API defines a set of capabilities that can be used to manage and interact with a MATTR VII tenant. This includes managing a Verifiable Credential across its lifecycle (issue-hold-verify) as well as various tenant administration and management tasks such as setting up a custom domain, creating DIDs and configuring issuance and verification workflows.
Refer to our API Changelog to see changes from previous versions.

Getting Started with our APIs

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

{
"audience": "YOUR_AUDIENCE_URL",
"url": "YOUR_AUTH_URL",
"tenant_subdomain": "YOUR_TENANT_SUBDOMAIN",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}

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

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

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

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

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

Pagination

Most list operations in the API enable cursor pagination using the cursor and limit query parameters:

Example on Retrieve List of Credentials

GET https://{tenant-url}/core/v2/credentials
?limit=100
&cursor=Y3JlYXRlZEF0PTIwMjAtMTAtMDhUMjMlM0ExMyUzQTE3Ljg5NtZGUxZWEyNzQ4MWI4
  • limit: determines how many entries are returned in that request, with a maximum value of 1000.
  • cursor: sets the location in the retrieved list to get the next batch of entries from. This is based on the returned nextCursor, found at the beginning of each returned range and identifies the last object in the list.

Requesting an entry after the last list value will return an empty data object:

{
"data": []
}

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

Authorization

Access to the API is granted by our authorization provider. Use the client_id and client_secret provided with your tenant details to make a request to receive a bearer token from the auth provider. This token must then be used as an authorization header for all requests to protected endpoints (this is required for the majority of operations).

bearerAuth

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

bearerAuthOpenIdCredentials

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Analytics

Retrieve events

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

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

Authorizations:
query Parameters
ids
Array of Array of strings

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

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

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

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

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

Example: categories=dcc
types
Array of Array of strings

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

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

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

Example:
dateTo
string <date-time>

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

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

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.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&limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Messaging

Sign a message

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

Analytic events

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

Sign message request

didUrl
required
string

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

payload
required
object (JSONObjectMessage)

A JSON Object plaintext message

Responses

Request samples

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

Response samples

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

Verify a message

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

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

Analytic events

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

Provide the JWS to verify

jws
string

JWS (JSON Web Siganture) in its compact form.

Responses

Request samples

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

Response samples

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

Encrypt a message

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

Analytic events

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

Encryption parameters

senderDidUrl
required
string

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

recipientDidUrls
required
Array of strings

The intended recepient's Subject DID.

payload
required
object

The message to be encrypted.

Responses

Request samples

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

Response samples

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

Decrypt a message

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

Analytic events

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

Decryption parameters

required
string or EncryptedMessage (object)

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

Responses

Request samples

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

Response samples

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

Send a message

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

Analytic events

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

Recipient DID.

string or object

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

Responses

Request samples

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

Response samples

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

Security

Create API Auth Token

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

The required client_id, client_secret, audience and authentication server are provided as part of onboarding. If you have not received your tenant details or have any other questions, please contact us before proceeding.

Request Body schema: application/json
client_id
required
string

Use the client_id value provided with your tenant details.

client_secret
required
string

Use the client_secret value provided with your tenant details.

audience
required
string

Use the audience value provided with your tenant details.

grant_type
required
string

Use client_credentials.

Responses

Request samples

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

Response samples

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

Custom Domain

Configure custom domain

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

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

Analytic events

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

The custom domain payload

name
required
string

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

logoUrl
required
string

Insert a URL for a logo that will be displayed to digital wallet holders when they receive credential offers or verification requests from your MATTR VII tenant. Must be an available and valid .png or .jpg file. For best results we recommend a 65px square image.

domain
required
string

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

Responses

Request samples

Content type
{}

Response samples

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

Retrieve custom domain

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

Analytic events

  • CONFIG_CUSTOM_DOMAIN_RETRIEVE_START
  • CONFIG_CUSTOM_DOMAIN_RETRIEVE_SUCCESS
  • CONFIG_CUSTOM_DOMAIN_RETRIEVE_FAIL
Authorizations:

Responses

Request samples

curl -i -X GET \
  'https://{tenantName}.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": true,
  • "verifiedAt": "2024-01-31T20:31:48.340Z"
}

Delete custom domain

Deletes the custom domain configuration on your tenant.

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

Analytic events

  • CONFIG_CUSTOM_DOMAIN_DELETE_START
  • CONFIG_CUSTOM_DOMAIN_DELETE_SUCCESS
  • CONFIG_CUSTOM_DOMAIN_DELETE_FAIL
Authorizations:

Responses

Request samples

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

Updates the custom domain configuration.

Analytic events

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

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

logoUrl
required
string

Insert a URL for a logo that will be displayed to digital wallet holders when they receive credential offers or verification requests from your MATTR VII tenant. Must be an available and valid .png or .jpg file. For best results we recommend a 65px square image.

domain
required
string

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

Responses

Request samples

Content type
application/json
{}

Response samples

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

Verify custom domain

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

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

Analytic events

  • CONFIG_CUSTOM_DOMAIN_VERIFY_START
  • CONFIG_CUSTOM_DOMAIN_VERIFY_SUCCESS
  • CONFIG_CUSTOM_DOMAIN_VERIFY_FAIL
Authorizations:

Responses

Request samples

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

DIDs

Create a DID

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

MATTR VII currently supports creating DIDs of the following methods:

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

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

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

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

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

Responses

Request samples

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

Response samples

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

Retrieve a list of DIDs

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

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

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

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

Analytics events

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

DID

Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9

Responses

Request samples

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

Response samples

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

Delete a DID

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

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

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

Well known DID configuration

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

Responses

Request samples

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

Response samples

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

Inboxes

Create an inbox

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

Analytic events

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

Inbox configuration

name
required
string non-empty

Inbox name.

Responses

Request samples

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

Response samples

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

List inboxes

Returns a list of all inboxes on the tenant.

Analytic events

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

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

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

Retrieves an inbox based on its ID.

Analytic events

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

Inbox ID

Responses

Request samples

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

Response samples

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

Update an inbox

Update the inbox configurations

Authorizations:
path Parameters
id
required
string

Inbox ID

Request Body schema: application/json

Updates an inbox name.

Analytic events

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

Responses

Request samples

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

Response samples

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

Delete an inbox

Deletes an inbox by providing its ID.

Analytic events

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

Inbox ID

Responses

Request samples

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

Register the provided DID to the requested inbox.

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

Analytic events

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

Requested inbox ID

Request Body schema: application/json

DID registration information

did
required
string

URI of the DID to register with this inbox.

jwt
string

Responses

Request samples

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

Response samples

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

Retrieve inbox DIDs

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

Analytic events

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

Requested inbox ID

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

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

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

Unregisters a DID from the requested inbox.

Analytic events

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

Requested inbox ID

did
required
string

DID

Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9

Responses

Request samples

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

Retrieving all the messages from an inbox

Analytic events

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

Requested inbox ID

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

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

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

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

Analytic events

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

Requested inbox ID

messageid
required
string

Requested message ID

Responses

Request samples

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

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

Analytic events

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

Requested inbox ID

messageid
required
string

Requested message ID

Responses

Request samples

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

Creates a new webhook for this tenant.

Analytic events

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

The webhook payload

events
required
Array of strings

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

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

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

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

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

Responses

Request samples

Content type
application/json
{}

Response samples

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

Retrieve all Webhooks

Retrieves a list of webhooks configured on the tenant.

Analytic events

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

Range size of returned webhook entries, default 100

Example: limit=2
cursor
string

Starting point for the range of webhook entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

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

Retrieve Webhook

Retrieve a specific Webhook by providing its ID.

Analytic events

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

The requested Webhook ID.

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

Responses

Request samples

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

Updates an existing Webhook by providing its ID.

Analytic events

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

Webhook ID

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

Update Webhook

events
required
Array of strings

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

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

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

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

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

Responses

Request samples

Content type
application/json
{}

Response samples

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

Delete Webhook

Deletes a Webhook by providing its ID.

Analytic events

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

Webhook ID

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

Responses

Request samples

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

Retrieve Webhook JWKs

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

Authorizations:

Responses

Request samples

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

Response samples

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

Ecosystems

Retrieve all ecosystems

Retrieves a list of ecosystems.

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/v1/ecosystems?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response samples

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

Create ecosystem

Creates an ecosystem.

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

The name of the ecosystem.

Responses

Request samples

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

Response samples

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

Retrieve ecosystem

Retrieves an ecosystem by its ID.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

Responses

Request samples

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

Response samples

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

Update ecosystem

Updates an ecosystem by its ID.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

Responses

Request samples

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

Response samples

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

Delete ecosystem

Deletes an ecosystem by its ID.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

Responses

Request samples

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

Response samples

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

Ecosystem Participants

Retrieve participants

Retrieves a list of participants from the requested ecosystem.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

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

Response samples

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

Create participant

Creates a participant in the requested ecosystem.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

Name to easily identify the participant.

required
object

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

  • Credentials are only valid in the ecosystem if they include an identifier of an issuer that is a participant in the ecosystem.
  • Verification requests are only valid in the ecosystem if they include an identifier of a verifier that is a participant in the ecosystem.
isIssuer
boolean
Default: false

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

isVerifier
boolean
Default: false

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

isIssuerConstrained
boolean
Default: true

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

isVerifierConstrained
boolean
Default: true

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

Responses

Request samples

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

Response samples

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

Retrieve participant

Retrieves a participant from the requested ecosystem by its ID.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

The UUID of the participant

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

Responses

Request samples

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

Response samples

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

Update participant

Updates a participant in the requested ecosystem by its ID.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

The UUID of the participant

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

Name to easily identify the participant.

required
object

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

  • Credentials are only valid in the ecosystem if they include an identifier of an issuer that is a participant in the ecosystem.
  • Verification requests are only valid in the ecosystem if they include an identifier of a verifier that is a participant in the ecosystem.
isIssuer
boolean
Default: false

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

isVerifier
boolean
Default: false

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

isIssuerConstrained
boolean
Default: true

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

isVerifierConstrained
boolean
Default: true

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

Responses

Request samples

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

Response samples

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

Delete participant

Deletes a participant in the requested ecosystem by its ID.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

The UUID of the participant

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

Responses

Request samples

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

Response samples

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

Ecosystem Credentials

Create credential type

Creates a new credential type in the requested ecosystem.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

The name of the credential

Responses

Request samples

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

Response samples

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

Retrieve credential types

Retrieves a list of credential types from the requested ecosystem.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

Range size of the list, default 100

Example: limit=2
cursor
string

Starting point for the list

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

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

Response samples

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

Retrieve credential type

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

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

The UUID of the credential

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

Responses

Request samples

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

Response samples

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

Delete credential type

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

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

The UUID of the credential

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

Responses

Request samples

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

Response samples

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

Ecosystem Issuer Policies

Retrieve issuer policy

Retrieves an ecosystem issuer policy by its ID.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

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

Accept-Encoding
string

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

Enum: "gzip" "deflate"

Responses

Request samples

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

Response samples

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

Create issuer policy

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

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

The UUID of the participant

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

Responses

Request samples

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

Response samples

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

Delete issuer policy

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

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

The UUID of the participant

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

The UUID of the credential

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

Responses

Request samples

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

Response samples

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

Ecosystem Verifier Policies

Retrieve verifier policy

Retrieves an ecosystem verifier policy by its ID.

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

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

Accept-Encoding
string

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

Enum: "gzip" "deflate"

Responses

Request samples

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

Response samples

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

Create verifier policy

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

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

The UUID of the participant

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

Responses

Request samples

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

Response samples

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

Delete verifier policy

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

Authorizations:
path Parameters
ecosystemId
required
string <uuid>

The UUID of the ecosystem

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

The UUID of the participant

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

The UUID of the credential

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

Responses

Request samples

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

Response samples

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

Web Credentials

Sign a Web Semantic Credential

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

Analytic events

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

Web Semantic Credential payload to sign

required
object
proofType
string

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

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

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

persist
boolean
Default: false

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

  • id
  • tag
  • credentialStatus
  • issuanceDate

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

revocable
boolean
Default: false

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

Responses

Request samples

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

Response samples

Content type
application/json
{}

Retrieve all credential data

Returns all available data for existing credentials:

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

Analytic events

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

Optional tag to filter on.

Example: tag=identifier123
type
string

Optional credential type to filter on.

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

Range size of returned credential entries, default 100

Example: limit=2
cursor
string

Starting point for the range of credential entries

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h

Responses

Request samples

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

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

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

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_RETRIEVE_START
  • CREDENTIAL_WEB_SEMANTIC_RETRIEVE_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_RETRIEVE_FAIL
Authorizations:
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
{}

Delete credential data

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

Removed credential data cannot be recovered.

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_DELETE_START
  • CREDENTIAL_WEB_SEMANTIC_DELETE_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_DELETE_FAIL
Authorizations:
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 providing its payload. The credential is verified against the following criteria:

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

Optional verification checks:

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

Analytic events

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

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

assertExpiry
boolean
Default: true

When set to true, verification will fail when expiry date has passed.

checkRevocation
boolean
Default: true

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

Responses

Request samples

Content type
application/json
{}

Response samples

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

Web Credentials configuration

Create a Web Credential configuration

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

Analytic events

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

The Credential Configuration payload

name
required
string

Insert a meaningful name for the credential. This string is displayed on the top part of the credential in the holder's digital wallet. Maximum length is 18 characters and as additional characters are not displayed on the credential.

description
string

Insert a meaningful description for the credential. This string is displayed below the name field on the credential in the holder's digital wallet. Maximum length is 38 characters as any additional characters are not displayed on the credential.

type
required
string [ 1 .. 1024 ] characters

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

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

Additional credential types that can be referenced.

Array of strings or objects

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

required
object

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

proofType
string

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

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

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

object

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

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

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

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

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

claimSourceId
string <uuid>

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

object

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

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Retrieve all Web Credential configurations

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

Analytic events

  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_START
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_WEB_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_FAIL
Authorizations:
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 Web Credential configuration

Retrieve a Web Credential configuration by providing its ID.

Analytic events

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

Web Credential configuration unique identifier

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

Responses

Request samples

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

Response samples

Content type
application/json
{}

Update a Web Credential configuration

Updates an existing Web Credential configuration by providing its ID.

Analytic events

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

Web Credential configuration unique identifier

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

Update a Credential Configuration

name
required
string

Insert a meaningful name for the credential. This string is displayed on the top part of the credential in the holder's digital wallet. Maximum length is 18 characters and as additional characters are not displayed on the credential.

description
string

Insert a meaningful description for the credential. This string is displayed below the name field on the credential in the holder's digital wallet. Maximum length is 38 characters as any additional characters are not displayed on the credential.

type
required
string [ 1 .. 1024 ] characters

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

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

Additional credential types that can be referenced.

Array of strings or objects

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

required
object

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

proofType
string

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

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

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

object

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

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

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

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

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