JSON credentials

Verify a JSON credential

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

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

Optional verification checks:

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

Analytic events

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

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

assertExpiry
boolean
Deprecated
Default: true

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

checkRevocation
boolean
Default: true

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

assertValidFrom
boolean
Default: true

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

assertValidUntil
boolean
Default: false

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

Responses
200

Verification completed

400

Bad Request

post/v2/credentials/web-semantic/verify
Request samples
application/json
{}
Response samples
application/json
{
  • "verified": true,
  • "reason": {
    }
}

Create a presentation template

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

Analytic events

  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_CREATE_START
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_CREATE_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_CREATE_FAIL
SecuritybearerAuth
Request
Request Body schema: application/json
required

The template

domain
required
string

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

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

name
required
string

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

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

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

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

Presentation template created

400

Bad request, Invalid request body

post/v2/credentials/web-semantic/presentations/templates
Request samples
application/json
{
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}
Response samples
application/json
{
  • "id": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}

Retrieve all presentation templates

Returns a list of all presentation templates on your tenant.

Analytic events

  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_LIST_START
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_LIST_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_LIST_FAIL
SecuritybearerAuth
Request
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
200

Presentation templates retrieved

get/v2/credentials/web-semantic/presentations/templates
Request samples
Response samples
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": [
    ]
}

Retrieve a presentation template

Retrieve an existing presentation template by its ID.

Analytic events

  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_START
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_RETRIEVE_FAIL
SecuritybearerAuth
Request
path Parameters
id
required
string

Presentation template ID

Responses
200

Presentation template retrieved

400

Invalid templateId parameter format

404

Not Found

get/v2/credentials/web-semantic/presentations/templates/{id}
Request samples
Response samples
application/json
{
  • "id": "64e45290-9980-11ea-b872-f1bee5fb328f",
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}

Delete a presentation template

Deletes an existing presentation template by its ID.

Analytic events

  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_DELETE_START
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_DELETE_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_DELETE_FAIL
SecuritybearerAuth
Request
path Parameters
id
required
string

Presentation template ID

Responses
204

Presentation template deleted

400

Invalid templateId parameter format.

404

Not Found

delete/v2/credentials/web-semantic/presentations/templates/{id}
Request samples
Response samples
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": [
    ]
}

Update a presentation template

Updates an existing presentation template by its ID.

Analytic events

  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_UPDATE_START
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_UPDATE_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_TEMPLATE_UPDATE_FAIL
SecuritybearerAuth
Request
path Parameters
id
required
string

Presentation template ID

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

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

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

name
required
string

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

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

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

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

OK

put/v2/credentials/web-semantic/presentations/templates/{id}
Request samples
application/json
{
  • "id": "string",
  • "domain": "string",
  • "name": "string",
  • "query": [
    ]
}
Response samples
application/json
{
  • "id": "64e45290-9980-11ea-b872-f1bee5fb328f",
  • "domain": "tenant.vii.mattr.global",
  • "name": "alumni_credential_request",
  • "query": [
    ]
}

Create a presentation request

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

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

Analytic events

  • PRESENTATION_WEB_SEMANTIC_REQUEST_CREATE_START
  • PRESENTATION_WEB_SEMANTIC_REQUEST_CREATE_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_REQUEST_CREATE_FAIL
SecuritybearerAuth
Request
Request Body schema: application/json
required

The presentation request payload

challenge
required
string

This unique identifier will be used to validate the presentation response sent to the configured callbackUrl. By comparing challenge with the challengeId value in the response, you can ensure it was sent by the intended MATTR VII tenant.

did
required
string

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

templateId
required
string

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

expiresTime
number

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

callbackUrl
required
string <uri>

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

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

    The callback URL will not be present directly in the signed presentation request. We highly recommend protecting the callback endpoint by including a unique identifier in the URL to create a unique callback URL for each request, which would make it hard to guess. We recommend the callback endpoint always responds with a 404 header to any unsuccessful calls.

Responses
201

Presentation request created

400

Bad Request

post/v2/credentials/web-semantic/presentations/requests
Request samples
application/json
{
  • "challenge": "64e45290-9980-11ea-b872-f1bee5fb328f",
  • "did": "did:key:z6Mkt7bFYc4V2HdAxwhMtaY6cgJckYXwhYdPLJCcnVqzrkpr",
  • "templateId": "64e45290-9980-11ea-b872-f1bee5fb328f",
  • "expiresTime": 1592955632103,
}
Response samples
application/json
{}

Verify a verifiable presentation

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

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

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

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

Analytic events

  • PRESENTATION_WEB_SEMANTIC_VERIFY_START
  • PRESENTATION_WEB_SEMANTIC_VERIFY_SUCCESS
  • PRESENTATION_WEB_SEMANTIC_VERIFY_FAIL
SecuritybearerAuth
Request
Request Body schema: application/json

Presentation to verify

required
object
challenge
string
domain
string
Responses
200

Presentation verification completed

400

Bad Request

post/v2/credentials/web-semantic/presentations/verify
Request samples
application/json
{}
Response samples
application/json
{
  • "verified": true
}