Learn

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,
  • "callbackUrl": "https://your-website.com/api/callback"
}
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
}
➔ Next to mDocs