The Platform Core API defines a set of capabilities that can be used to manage a tenant of the MATTR Platform.
The API can be used to manage Decentralised Identifiers, issue Credentials directly or using OpenID Connect flows, and verify Messages signed with DIDs.
Most list operations in the API use pagination that can be controlled by a cursor method using the cursor
and limit
query parameters.
Example on Retrieve List of Credentials
GET https://{tenant-subdomain}.vii.mattr.global/core/v1/credentials
?limit=100
&cursor=Y3JlYXRlZEF0PTIwMjAtMTAtMDhUMjMlM0ExMyUzQTE3Ljg5NtZGUxZWEyNzQ4MWI4
- The
nextCursor
is found at the start of each returned range of credential entries and identifies the last object in the list. - The
limit
determines how many entries are returned in that request, with a maximum value of 1000.
Requesting a page after the last value in the list will return an empty data
object.
{
"data": []
}
Not using a query parameter defaults the response to return the first range of credential entries with a limit of 100.
Access to the API is granted by our authorization provider, as part of onboarding you will be provided with client credentials to make a call to the auth provider and receive a bearer token.
This token is then used in an authorization
header on all calls identified as requiring bearerAuth
(this is required for the majority of management operations).
Create API Auth Token
Authorization endpoint for gaining token used for API requests requiring bearerAuth
.
You will be provided the required client_id
and client_secret
as part of onboarding.
Request Body schema: application/json
client_id required | string |
client_secret required | string |
audience required | string |
grant_type required | string |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "client_id": "htf792W4p4MedZbnoWAs51EfqUt4d2",
- "client_secret": "d3fYDX7FjPg1D1h2viARXsolPByQ9vMfg8LHylBy8F4s5KJLB4HhHGOxxqJnSj3G",
- "grant_type": "client_credentials"
}
Response samples
- 200
- 401
{- "access_token": "s2dgbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6s2dcaEROemRDf5gbRVEwTTVSVFE0TmtZME9UZzVNVEpDTlVJNFJqRTBPREExTmpZMk1qazFPQSJ9",
- "expires_in": 86400,
- "token_type": "Bearer"
}
Create custom domain
A custom domain allows the display of your credentials or presentation requests to be rendered under the domain your preference as a tenant on the Mattr VII platform.
The verifiable custom domain can be mapped with that of the issuer or verifier stated in a credential or presentation and allow for the following attributes to be defined and returned:
- Organization Name
- Domain Name
- Logo
- Home Page
Returns
On Success, the response from the endpoint always include the Custom Domain
Authorizations:
Request Body schema: application/jsonapplication/jsonapplication/xml
The custom domain payload
name required | string Name of the custom domain |
logoUrl required | string Url for the domain logo |
domain required | string New domain |
homepage required | string Homepage for the url |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "name": "Site Worker Cert",
- "domain": "ssi.siteworkercert.com",
}
Response samples
- 201
- 400
{- "name": "Site Worker Cert",
- "domain": "ssi.sitesafe.org.nz",
- "verificationToken": "SdsswaSADasdASdasdasdsa",
- "isVerified": false,
- "verifiedAt": null
}
Retrieve custom domain
Retrieve the custom domain information and it's verification status for your Mattr VII tenant.
Authorizations:
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/config/domain' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 404
{- "name": "Site Worker Cert",
- "domain": "ssi.siteworkercert.com",
- "verificationToken": "SdsswaSADasdASdasdasdsa",
- "isVerified": false,
- "verifiedAt": null
}
Delete custom domain
Delete the custom domain.
By deleting your existing custom domain it will break the linkage with any credentials issued under the custom domain, in turn causing issues when holders of those credentials go to present them.
Authorizations:
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X DELETE \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/config/domain' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 404
{- "code": "string",
- "message": "string",
- "details": [
- {
- "value": "string",
- "msg": "Invalid value",
- "param": "id",
- "location": "body"
}
]
}
Update custom domain
Update the custom domain.
Follows the same structure as the Create a Custom Domain endpoint.
Authorizations:
Request Body schema: application/json
id | string |
name required | string Name of the custom domain |
logoUrl required | string Url for the domain logo |
domain required | string New domain |
homepage required | string Homepage for the url |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "name": "Site Worker Cert",
- "domain": "ssi.siteworkercert.com",
}
Response samples
- 200
- 404
{- "name": "Site Worker Cert",
- "domain": "ssi.siteworkercert.com",
- "verificationToken": "SdsswaSADasdASdasdasdsa",
- "isVerified": true,
- "verifiedAt": "2021-04-15T07:37:25.008Z"
}
Verify custom domain
Verifies that you have control of the custom domain by examining the TXT record of the domain.
Authorizations:
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X POST \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/config/domain/verify' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 400
- 404
{- "code": "string",
- "message": "string",
- "details": [
- {
- "value": "string",
- "msg": "Invalid value",
- "param": "id",
- "location": "body"
}
]
}
Well known DID configuration
Returns a list of Decentralized Identifier (DID) Configuration entries from the tenant.
See https://identity.foundation/.well-known/resources/did-configuration/
These entries are automatically configured for all DIDs created by the tenant and is used for any party wanting to establish the relationship between domain ownership and the DIDs by exposing cryptographic proofs.
This endpoint is unprotected, public facing and can be deterministically found at the root of the tenant subdomain or alias by any party wishing to discover the domain to DID relationship.
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/.well-known/did-configuration'
Response samples
- 200
{- "entries": [
- {
- "type": [
- "VerifiableCredential",
- "DomainLinkageCredential"
], - "issuer": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
- "issuanceDate": "2020-11-01T21:33:38.398Z",
- "credentialSubject": {
- "id": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
- "origin": "tenant.vii.mattr.global"
}, - "proof": {
- "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..sOuFZV7lrUdxzOaRrCYoD9bbgxp3oEX1fceFFwxekjvJBzbI_ZzKL8-vPWOoFY200KTPwLYcEPhto0GQfM0iDg",
- "type": "Ed25519Signature2018",
- "created": "2020-11-01T21:33:38Z",
- "proofPurpose": "assertionMethod",
- "verificationMethod": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5"
}
}, - {
- "type": [
- "VerifiableCredential",
- "DomainLinkageCredential"
], - "issuer": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
- "issuanceDate": "2020-11-01T21:33:38.427Z",
- "credentialSubject": {
- "id": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
- "origin": "product-team.platform.staging.mattrlabs.io"
}, - "proof": {
- "type": "BbsBlsSignature2020",
- "created": "2020-11-01T21:33:38Z",
- "proofValue": "itoN9nPf6ut0/IxkNp+qesJOju9hV1BYxFMkP4VynqUxFalmQV4PQ6wJhqz5KJppC39+VL+19CxVjPXUXaIDVGRs7WPDGbLaGeViu1Mm4nZCgJbptdw8HOkkpZZ21SCaTN+bok2IG5XRH+QsBWH/cA==",
- "proofPurpose": "assertionMethod",
- "verificationMethod": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC75v2eWSVhTC9XtyYci1cdrHNze4Wwzgv92GUDXeYQEkfZuu2CavRBVFkk9mnpToxiUMacjgYAx9JBmuoJXWc7YCRDDjTD5ocunta9DJrdmgCdAmuFCUfBPTo4GAnTY7x4582"
}
}
]
}
Resolve a DID
When the DID is retrieved by the DID provided in the path, the DID Document is also attempted to be resolved by using the DID method and method identifier, this may involve a network call depending on the method involved.
Example:
did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9
- the public key is encapsulated in the DID
did:ion:EiBbvWpBHPql_2W9sObr4vPFl9k9InEDYOEDXvPPRDRyBg
- will be resolved on the ION network
did:web:mattr.global
- will be resolved by accessing the /.well-known/did.json
of the domain
Returns
If the DID Document is publicly resolvable it is returned along with meta-data already held about the DID by the tenant;
didDocument
: See our tutorials on MATTR Learn to understand more about the anatomy of the DID Document for each method.registrationStatus
: Ledger-based DIDs may incur a lag in processing to the ledger. Also for DIDs that require additional actions (e.g.did:web
) this status will be update fromPROCESSING
toCOMPLETED
once publicly resolvable.localMetadata
: This includes the initial DID document that the platform expects to find publicly resolvable.
Authorizations:
path Parameters
id required | string <did> DID Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9 |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/dids/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 404
{- "did": "did:web:organization.com",
- "registrationStatus": "COMPLETED",
- "localMetadata": {
- "keys": [
- {
- "didDocumentKeyId": "did:web:organization.com#2vcj3MjR4d",
- "kmsKeyId": "a0cba537-ffe1-486d-aedd-6ead80e75519"
}, - {
- "didDocumentKeyId": "did:web:organization.com#CU6dJt9p8t",
- "kmsKeyId": "250c4e1f-bae3-44ca-9f4e-4f7ff15851e2"
}
], - "registered": 1674421454614,
- "initialDidDocument": {
- "id": "did:web:organization.com",
- "publicKey": [
- {
- "id": "did:web:organization.com#2vcj3MjR4d",
- "controller": "did:web:organization.com",
- "type": "Ed25519VerificationKey2018",
- "publicKeyBase58": "2vcj3MjR4dSKq5asFQ9oor7iZsqTKTfBpjLHgaP15Y24"
}
], - "authentication": [
- "did:web:organization.com#2vcj3MjR4d"
], - "assertionMethod": [
- "did:web:organization.com#2vcj3MjR4d"
], - "capabilityDelegation": [
- "did:web:organization.com#2vcj3MjR4d"
], - "capabilityInvocation": [
- "did:web:organization.com#2vcj3MjR4d"
], - "keyAgreement": [
- {
- "id": "did:web:organization.com#CU6dJt9p8t",
- "controller": "did:web:organization.com",
- "type": "X25519KeyAgreementKey2019",
- "publicKeyBase58": "CU6dJt9p8twE4hmyGVFbVpUMmu6G732bVgD1tNupwYY7"
}
]
}
}
}
Delete a DID
Deletes a DID and all associated metadata including the Private keys from the platform and KMS.
For ledger-based DIDs the public DID Document will still be available.
For did:web
you can remove the did.json
from your hosted domain.
Authorizations:
path Parameters
id required | string <did> DID Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9 |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X DELETE \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/dids/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 400
- 404
{- "code": "BadRequest",
- "message": "Validation Error",
- "details": [
- {
- "value": "xxx",
- "msg": "Invalid value",
- "param": "id",
- "location": "params"
}
]
}
Create a DID
Takes a supported DID Method and generates keys and associated information for a new DID and registers the DID Document if applicable.
Methods supported:
- key
- web
- ion
Options: The options parameter is used to define further configuration when creating the DID, the available options vary between methods.
Note: W3C DIDs are an emerging standard at the W3C, DIDs issued during a trial on the MATTR VII platform may be subject to change, as you move into production workloads please get in touch to discuss your needs.
Creating did:key
A DID with a DID method of key can be created.
If no options are provided, a DID will be created with an ed25519 key type.
If the key type in options is set to bls12381g2
a DID will be created with a BLS key type which supports BBS+ signatures for issuing ZKP-enabled credentials.
A DID Key created with an experimental
bls12381g2
key type can only be used for issuing credentials.
Creating did:web
A DID with a DID method of web can be created by specifying the domain
where the DID document is going to be hosted in the options
body.
If the key type in options is set to P-256
a DID will be created with a P-256 key type which compact credentials.
The returned initial DID Document then needs to be hosted so that it is accessible from the domain provided in the options, e.g. https://mattr.global/.well-known/did.json.
When the DID Document is not available for download from the domain, the Registration Status of the DID is PROCESSING.
Once the DID Document can be downloaded from the domain, the Registration Status will be COMPLETED.
Note that the tenant will be able to prove ownership of the keys associated with the did:web DID Document through the well-known endpoint, i.e. https://tenant.vii.mattr.global/.well-known/did-configuration, while the DID Document hosted on the domain links the DID to a domain.
Creating did:ion
A DID with a DID method of ion can be created.
Public DID Document is anchored by batching using the ION network, due to the lag incurred in registering the DID Document, which may take between 20-120 minutes, the registrationStatus
will remain as PROCESSING
until the DID Document can be retrieved from the public nodes.
Note: The creation of ION DIDs during a trial of the MATTR VII platform may be subject to change, as you move into production workloads please get in touch to discuss your needs.
Returns
The DID, associated metadata and registration status.
Unsupported Methods result in a 400 response with an "Invalid value" message.
Authorizations:
Request Body schema: application/json
Options for creating the decentralized identifier
method required | string Enum: "key" "web" "ion" |
options | object non-empty To define a key type for a did:key or to define a domain for did:web |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "method": "web",
- "options": {
- "url": "organization.com"
}
}
Response samples
- 201
- 400
{- "did": "did:web:organization.com",
- "registrationStatus": "COMPLETED",
- "localMetadata": {
- "keys": [
- {
- "didDocumentKeyId": "did:web:organization.com#2vcj3MjR4d",
- "kmsKeyId": "a0cba537-ffe1-486d-aedd-6ead80e75519"
}, - {
- "didDocumentKeyId": "did:web:organization.com#CU6dJt9p8t",
- "kmsKeyId": "250c4e1f-bae3-44ca-9f4e-4f7ff15851e2"
}
], - "registered": 1674421454614,
- "initialDidDocument": {
- "id": "did:web:organization.com",
- "publicKey": [
- {
- "id": "did:web:organization.com#2vcj3MjR4d",
- "controller": "did:web:organization.com",
- "type": "Ed25519VerificationKey2018",
- "publicKeyBase58": "2vcj3MjR4dSKq5asFQ9oor7iZsqTKTfBpjLHgaP15Y24"
}
], - "authentication": [
- "did:web:organization.com#2vcj3MjR4d"
], - "assertionMethod": [
- "did:web:organization.com#2vcj3MjR4d"
], - "capabilityDelegation": [
- "did:web:organization.com#2vcj3MjR4d"
], - "capabilityInvocation": [
- "did:web:organization.com#2vcj3MjR4d"
], - "keyAgreement": [
- {
- "id": "did:web:organization.com#CU6dJt9p8t",
- "controller": "did:web:organization.com",
- "type": "X25519KeyAgreementKey2019",
- "publicKeyBase58": "CU6dJt9p8twE4hmyGVFbVpUMmu6G732bVgD1tNupwYY7"
}
]
}
}
}
Retrieve a list of DIDs
Returns a list of all DIDs (Decentralized Identifiers) managed by the tenant and their associated meta-data.
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
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/dids?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
{- "data": [
- {
- "did": "did:web:organization.com",
- "localMetadata": {
- "keys": [
- {
- "kmsKeyId": "a0cba537-ffe1-486d-aedd-6ead80e75519",
- "didDocumentKeyId": "did:web:organization.com#2vcj3MjR4d"
}, - {
- "kmsKeyId": "250c4e1f-bae3-44ca-9f4e-4f7ff15851e2",
- "didDocumentKeyId": "did:web:organization.com#CU6dJt9p8t"
}
], - "registered": 1674421454614,
- "initialDidDocument": {
- "id": "did:web:organization.com",
- "publicKey": [
- {
- "id": "did:web:organization.com#2vcj3MjR4d",
- "type": "Ed25519VerificationKey2018",
- "controller": "did:web:organization.com",
- "publicKeyBase58": "2vcj3MjR4dSKq5asFQ9oor7iZsqTKTfBpjLHgaP15Y24"
}
], - "keyAgreement": [
- {
- "id": "did:web:organization.com#CU6dJt9p8t",
- "type": "X25519KeyAgreementKey2019",
- "controller": "did:web:organization.com",
- "publicKeyBase58": "CU6dJt9p8twE4hmyGVFbVpUMmu6G732bVgD1tNupwYY7"
}
], - "authentication": [
- "did:web:organization.com#2vcj3MjR4d"
], - "assertionMethod": [
- "did:web:organization.com#2vcj3MjR4d"
], - "capabilityDelegation": [
- "did:web:organization.com#2vcj3MjR4d"
], - "capabilityInvocation": [
- "did:web:organization.com#2vcj3MjR4d"
]
}
}
}, - {
- "did": "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ",
- "localMetadata": {
- "keys": [
- {
- "kmsKeyId": "2462a440-ef70-413b-8e73-0b2905a73562",
- "didDocumentKeyId": "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ#z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ"
}, - {
- "kmsKeyId": "e65e6545-1ba0-4959-8272-db22a46f2e34",
- "didDocumentKeyId": "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ#z6LSsfqtdz5mtaGRTZrGwhzK73xDYAtack5AHKcakR1eco7K"
}
], - "registered": 1671586060525,
- "initialDidDocument": {
- "id": "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ",
- "publicKey": [
- {
- "id": "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ#z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ",
- "type": "Ed25519VerificationKey2018",
- "controller": "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ",
- "publicKeyBase58": "Bqf3SpwXEypMQq9txNrURNy1kZXzAPXKVwinChGztncB"
}
], - "keyAgreement": [
- {
- "id": "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ#z6LSsfqtdz5mtaGRTZrGwhzK73xDYAtack5AHKcakR1eco7K",
- "type": "X25519KeyAgreementKey2019",
- "controller": "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ",
- "publicKeyBase58": "Gzfj7gGuo7YgNBUWR4UMnTjjh2MTv8u1QLtuFxN7uRLZ"
}
], - "authentication": [
- "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ#z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ"
], - "assertionMethod": [
- "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ#z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ"
], - "capabilityDelegation": [
- "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ#z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ"
], - "capabilityInvocation": [
- "did:key:z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ#z6MkqHv635BxaXJpXKzbdwpKGUX1a8oqaGmgBxdi2yF1p1PZ"
]
}
}
}, - {
- "did": "did:ion:EiCxlIzULX6md4wBggQVdzuDPgy58cMW_H9CQ6hkW91YtQ",
- "localMetadata": {
- "keys": [
- {
- "kmsKeyId": "0d3c95ee-ff93-4778-96b0-3e57dd153fba",
- "didDocumentKeyId": "did:ion:EiCxlIzULX6md4wBggQVdzuDPgy58cMW_H9CQ6hkW91YtQ#zUC75TxeBMRgUjgUKJg4"
}, - {
- "kmsKeyId": "a90ea7e7-3d97-419b-93ec-ed159d1d18b6",
- "didDocumentKeyId": "did:ion:EiCxlIzULX6md4wBggQVdzuDPgy58cMW_H9CQ6hkW91YtQ#z6LSsfkgE4dWgrPZghe2"
}, - {
- "kmsKeyId": "85542839-2a9e-41bf-b479-9bca2ed2985c",
- "authorizedDidOperations": [
- "Recover"
]
}, - {
- "kmsKeyId": "fe83a58c-f27f-472f-b3f5-23676f8b5abd",
- "authorizedDidOperations": [
- "Update"
]
}
], - "registered": 1671579338301,
- "initialDidDocument": {
- "id": "did:ion:EiCxlIzULX6md4wBggQVdzuDPgy58cMW_H9CQ6hkW91YtQ",
- "@context": [
- {
- "@base": "did:ion:EiCxlIzULX6md4wBggQVdzuDPgy58cMW_H9CQ6hkW91YtQ"
}
], - "keyAgreement": [
- "#z6LSsfkgE4dWgrPZghe2"
], - "authentication": [
- "#zUC75TxeBMRgUjgUKJg4"
], - "assertionMethod": [
- "#zUC75TxeBMRgUjgUKJg4"
], - "verificationMethod": [
- {
- "id": "#zUC75TxeBMRgUjgUKJg4",
- "type": "JsonWebKey2020",
- "controller": "did:ion:EiCxlIzULX6md4wBggQVdzuDPgy58cMW_H9CQ6hkW91YtQ",
- "publicKeyJwk": {
- "x": "jSo1fcYfZ9HLPP9nK2ZS7NR9yad9AEfIzbhQ2NvbkxzqSCbjMZunOPS5J4kkGZ6eFSR1qLkT9Pb34uqblyJo4JpbhTVt7K1NdV3ySdkAp6qXKoSqBAVNxC9exI9SQ8Jj",
- "crv": "Bls12381G2",
- "kty": "OKP"
}
}, - {
- "id": "#z6LSsfkgE4dWgrPZghe2",
- "type": "JsonWebKey2020",
- "controller": "did:ion:EiCxlIzULX6md4wBggQVdzuDPgy58cMW_H9CQ6hkW91YtQ",
- "publicKeyJwk": {
- "x": "7Z9NYlrWp9fXSNplf8zUZcsIoj_CB7_tRG3oyQmu9UU",
- "crv": "X25519",
- "kty": "OKP"
}
}
], - "capabilityDelegation": [
- "#zUC75TxeBMRgUjgUKJg4"
], - "capabilityInvocation": [
- "#zUC75TxeBMRgUjgUKJg4"
]
}
}
}
], - "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}
Create an inbox
An inbox will hold messages for DIDs that are registered with the inbox
Authorizations:
Request Body schema: application/json
Inbox configuration
name required | string non-empty |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "name": "YOUR_INBOX"
}
Response samples
- 201
- 400
{- "id": "string",
- "name": "string"
}
List inboxes
Returns a list of all registered inboxes for the tenant
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
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/messaging/inboxes?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
{- "data": [
- {
- "id": "string",
- "name": "string"
}, - {
- "id": "string",
- "name": "string"
}
], - "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}
Retrieve an inbox name
Returns a single inbox based on the Inbox ID
Authorizations:
path Parameters
id required | string Inbox ID |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/messaging/inboxes/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 400
- 404
{- "id": "string",
- "name": "string"
}
Update an inbox
Update the inbox configurations
Authorizations:
path Parameters
id required | string Inbox ID |
Request Body schema: application/json
Update Inbox configuration
name required | string non-empty |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "name": "string"
}
Response samples
- 200
- 400
- 404
{- "id": "string",
- "name": "string"
}
Delete an inbox
Deletes a specific inbox
Authorizations:
path Parameters
id required | string Inbox ID |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X DELETE \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/messaging/inboxes/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 400
- 404
{- "code": "BadRequest",
- "message": "Validation Error",
- "details": [
- {
- "value": "notUUIDvalue",
- "msg": "Invalid value",
- "param": "inboxId",
- "location": "params"
}
]
}
Register DID with an inbox
This endpoint is responsible for registering DIDs to a specific Inbox. Currently, DID registration with inboxes is limited to did:key
Authorizations:
path Parameters
id required | string Inbox ID |
Request Body schema: application/json
DID registration information
did required | string |
jwt | string |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "did": "string",
- "jwt": "string"
}
Response samples
- 201
- 400
- 404
{- "did": "string"
}
List DIDs in an inbox
Returns a list of all DIDs for the specific Inbox
Authorizations:
path Parameters
id required | string Inbox ID |
query Parameters
limit | number [ 1 .. 1000 ] Default: 100 Range size of the list, default 100 Example: limit=2 |
cursor | string Starting point for the list Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/messaging/inboxes/:id/dids?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 400
- 404
{- "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
- "data": [
- "did:key:did1",
- "did:key:did2",
- "did:key:did3"
]
}
Unregister DID with an inbox
Unregister a DID from a specific inbox
Authorizations:
path Parameters
id required | string Inbox ID |
did required | string DID Example: did:key:z6Mkjr7vfzBfamiN6Wi6cyQUgTq6CEMXP1MzWQawsUEXJoa9 |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X DELETE \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/messaging/inboxes/:id/dids/:did' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 400
- 404
{- "code": "BadRequest",
- "message": "Validation Error",
- "details": [
- {
- "value": "notUUIDvalue",
- "msg": "Invalid value",
- "param": "inboxId",
- "location": "params"
}
]
}
List inbox messages
List of inbox messages
Authorizations:
path Parameters
id required | string Inbox ID |
query Parameters
limit | number [ 1 .. 1000 ] Default: 100 Range size of the list, default 100 Example: limit=2 |
cursor | string Starting point for the list Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/messaging/inboxes/:id/messages?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 400
- 404
{- "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
- "data": [
- {
- "name": "string",
- "createdAt": "2019-08-24",
- "id": "string",
- "inboxId": "string",
- "payload": "string"
}, - {
- "name": "string",
- "createdAt": "2019-08-24",
- "id": "string",
- "inboxId": "string",
- "payload": "string"
}
]
}
Retrieve a message
Returns an inbox message
Authorizations:
path Parameters
id required | string Inbox ID |
messageid required | string Message ID |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/messaging/inboxes/:id/messages/:messageid' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 400
- 404
{- "name": "string",
- "createdAt": "2019-08-24",
- "id": "string",
- "inboxId": "string",
- "payload": "string"
}
Delete a message from inbox
Deletes an inbox message
Authorizations:
path Parameters
id required | string Inbox ID |
messageid required | string Message ID |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X DELETE \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/messaging/inboxes/:id/messages/:messageid' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 400
- 404
{- "code": "BadRequest",
- "message": "Validation Error",
- "details": [
- {
- "value": "notUUIDvalue",
- "msg": "Invalid value",
- "param": "inboxId",
- "location": "params"
}
]
}
Sign a message
Creates a signed message in the form of a JWS (JSON Web Signature) using the a specific Key from the DID (Decentralized Identifier) supplied in the request.
didUrl
must be a reference to a key that supports signing.
Use the authentication
key value from the DID Document.
Simply put, from your DID document, you can find it in DID.localMetadata.initialDidDocument.authentication[0]
{
"did": "did:web:organization.com",
"registrationStatus": "COMPLETED",
"localMetadata": {
"keys": [
{
"didDocumentKeyId": "did:web:organization.com#2vcj3MjR4d",
"kmsKeyId": "a0cba537-ffe1-486d-aedd-6ead80e75519"
},
{
"didDocumentKeyId": "did:web:organization.com#CU6dJt9p8t",
"kmsKeyId": "250c4e1f-bae3-44ca-9f4e-4f7ff15851e2"
}
],
"registered": 1674421454614,
"initialDidDocument": {
"@context": "https://w3.org/ns/did/v1",
"id": "did:web:organization.com",
"publicKey": [
{
"id": "did:web:organization.com#2vcj3MjR4d",
"controller": "did:web:organization.com",
"type": "Ed25519VerificationKey2018",
"publicKeyBase58": "2vcj3MjR4dSKq5asFQ9oor7iZsqTKTfBpjLHgaP15Y24"
}
],
"authentication": [
"did:web:organization.com#2vcj3MjR4d"
],
"assertionMethod": [
"did:web:organization.com#2vcj3MjR4d"
],
"capabilityDelegation": [
"did:web:organization.com#2vcj3MjR4d"
],
"capabilityInvocation": [
"did:web:organization.com#2vcj3MjR4d"
],
"keyAgreement": [
{
"id": "did:web:organization.com#CU6dJt9p8t",
"controller": "did:web:organization.com",
"type": "X25519KeyAgreementKey2019",
"publicKeyBase58": "CU6dJt9p8twE4hmyGVFbVpUMmu6G732bVgD1tNupwYY7"
}
]
}
}
}
Returns
A JWS in compact serialization form signed by the did supplied in the request
Authorizations:
Request Body schema: application/json
Sign message request
didUrl required | string The did keyId that will be used to sign the message with. |
payload required | object (JSONObjectMessage) A JSON Object plaintext message |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "didUrl": "did:web:organization.com#2vcj3MjR4d",
- "payload": {
- "msg": "this is a message"
}
}
Response samples
- 200
- 400
"eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDprZXk6ejZNa21mazNtMldIQlVxVm94SlZ3R1NQejVrYmFKNnpBMXRwN1JRWUJiUUdtczNoI3o2TWttZmszbTJXSEJVcVZveEpWd0dTUHo1a2JhSjZ6QTF0cDdSUVlCYlFHbXMzaCJ9.eyJtc2ciOiJUaGlzIGlzIGEgcGF5bG9hZCJ9.5E9qEmmSOMHLABAr4A9VzuNKFaO4EDo2GSCMoxQm9zsE7eCmEEuaAxtNhOUdd-Wvj64vqBBVl84XB1Yg7X9wBg"
Verify a message
Provide a signed payload in the form of a JWS (JSON Web Signature) that has been signed by a DID (Decentralized Identifier) and get a response indicating if the signature verification was successful and the DID that was used to originally sign the payload.
One use case for verifying a JWS with a DID is when the Mobile Wallet App sends a Request Object to an OpenID Provider as part of the Authorization Code Flow (as per https://openid.net/specs/openid-connect-core-1_0-final.html#RequestObject). The Request Object is wrapped in a JWS with a signature that is generated from the Subject DID on the mobile app. Therefore verifying the JWS proves that the mobile app has access to the private key of the Subject DID.
Returns
Indicates if the JWS payload was untampered and that the signature is valid by verifying that the kid in the JWS header is the same as the iss
value in the Request Object, which could for instance be the Subject DID.
The DID used is returned as both the full didUrl
including fragment pointer to the DID Document and the did
which can be used for Credential creation.
Authorizations:
Request Body schema: application/json
JWS to verify
jws | string Compact form of JWS |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
Response samples
- 200
- 400
{- "payload": "payload",
- "didUrl": "did:web:organization.com#2vcj3MjR4d",
- "did": "did:web:organization.com",
- "verified": true,
- "signerPublicJwk": {
- "kty": "OKP",
- "crv": "Ed25519",
- "x": "oQvDM6MvUdcgRCqKGJOgteRC9U06_x7bFtY0T-MJ1rQ"
}
}
Encrypt a message
Encrypts a payload using a JWM format.
The senderDidUrl
must be a reference to a key that supports key agreement.
Use the id
value from the keyAgreement
list in the DID Document.
Simply put, you can find the value to use as senderDidUrl
from DID.localMetadata.initialDidDocument.keyAgreement[0].id
{
"did": "did:web:organization.com",
"registrationStatus": "PROCESSING",
"localMetadata": {
"keys": [
{
"didDocumentKeyId": "did:web:organization.com#2vcj3MjR4d",
"kmsKeyId": "a0cba537-ffe1-486d-aedd-6ead80e75519"
},
{
"didDocumentKeyId": "did:web:organization.com#CU6dJt9p8t",
"kmsKeyId": "250c4e1f-bae3-44ca-9f4e-4f7ff15851e2"
}
],
"registered": 1674421454614,
"initialDidDocument": {
"@context": "https://w3.org/ns/did/v1",
"id": "did:web:organization.com",
"publicKey": [
{
"id": "did:web:organization.com#2vcj3MjR4d",
"controller": "did:web:organization.com",
"type": "Ed25519VerificationKey2018",
"publicKeyBase58": "2vcj3MjR4dSKq5asFQ9oor7iZsqTKTfBpjLHgaP15Y24"
}
],
"authentication": [
"did:web:organization.com#2vcj3MjR4d"
],
"assertionMethod": [
"did:web:organization.com#2vcj3MjR4d"
],
"capabilityDelegation": [
"did:web:organization.com#2vcj3MjR4d"
],
"capabilityInvocation": [
"did:web:organization.com#2vcj3MjR4d"
],
"keyAgreement": [
{
"id": "did:web:organization.com#CU6dJt9p8t",
"controller": "did:web:organization.com",
"type": "X25519KeyAgreementKey2019",
"publicKeyBase58": "CU6dJt9p8twE4hmyGVFbVpUMmu6G732bVgD1tNupwYY7"
}
]
}
}
}
Returns
Authorizations:
Request Body schema: application/json
Encryption params
senderDidUrl required | string |
recipientDidUrls required | Array of strings |
payload required | object |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "senderDidUrl": "did:web:organization.com#CU6dJt9p8t",
- "recipientDidUrls": [
- "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d",
- "did:key:z6MkgxxdrThaRd7HbeAA4pYEwAgKT6ZXy2aNTcPkmeF1yWHN"
], - "payload": {
- "id": "731961f2-bdc3-4f1e-8d59-cc308fd60ec8",
- "from": "did:web:organization.com",
- "created_time": "1616466734",
- "body": {
- "uri": "openid://discovery?issuer=https://tenant.vii.mattr.global/ext/oidc/v1/issuers/0dceeddd-f717-4bf2-b520-b3ddcd104a60"
}
}
}
Response samples
- 200
- 400
{- "jwe": {
- "protected": "eyJhbGciOiJYQzIwUCJ9",
- "recipients": [
- {
- "header": {
- "alg": "ECDH-1PU+A256KW",
- "kid": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d#z6LSsvqSJkBvVEsDC8cxMHuQ3sKoLRMXB1MdtoLrMUq6A8Rg",
- "epk": {
- "kty": "OKP",
- "crv": "x25519",
- "x": "JOLnYaD7L-Rszz7fczPhn6MkNre25PUsztzB1RHoz14"
}, - "skid": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v#z6LScyz3YLToyoKwZE6Tfq65hgZUkZdHrC4ZqohcUH9X6Twx"
}, - "encryption_key": "ag5iKzjJOth9Wa68dCVKJW_vnO_Ga0zSJgQp5rIUg69HCzIjuNYhDg"
}, - {
- "header": {
- "alg": "ECDH-1PU+A256KW",
- "kid": "did:key:z6MkgxxdrThaRd7HbeAA4pYEwAgKT6ZXy2aNTcPkmeF1yWHN#z6LSgDiT1CkducmcSPaq9E1Uj1qdSXBjsUNqqLQLrUu8EHWd",
- "epk": {
- "kty": "OKP",
- "crv": "x25519",
- "x": "gDYW7rhG3cBqFp9trFETtlut6QJxYVVSoVWL7eN1bzE"
}, - "skid": "did:key:z6MkreuqFq6WrwozTeGKuUDz8bniTFRNAg8f3ZB862YdLp7v#z6LScyz3YLToyoKwZE6Tfq65hgZUkZdHrC4ZqohcUH9X6Twx"
}, - "encryption_key": "F5R5ZW7Yk7_iWT5kUWqv3w_tLI7V86tLRthjy_SSbGQ2pFyXKni_gA"
}
], - "ciphertext": "xpW-D6sDPpWc_jk87nEyxPX7JQV8_OZpaQft7ySQ5XmNhoj-lQyDkXDncOCyhB7yMSdZrRBNQjKxlEbpY_WLk1hBoWfsTeszVSAuFbX_VKUSJ7GR6rcnWGVNgDfKS8GsyC_owtswXatkF_65_mzFOygctkUmd2eI5bcpQpWjhw2vqnvnWkb7l2J27aWFF_c9cu52dB559j8lwLYyYC9oSMgV5piB6ppfrWBGo_DigjxvJcAYcjFYqFcT6A1nphPhwVTQ2HNfJodbQoseHub8UQdG4qAOcggq5DI84tbqor1SU9rdPH03jPkLgoO_aeXyJg5meITXoFSiu_tRfvf8QQ6vKq6pkTTXs8zKXcBCGhGIyKBNBG4R4RIY1UffTMnJQQQGBble3P06pGOnsnSop0BtygelB9M0ZEwnAUSAQqN1RR4AQwWcn9nH6hHEu1pMhSvhCuFNAPWS-hg24JGGw8Xe3EEZlLH0PM8qpUAfksPq",
- "iv": "FJq5zKvuPiUQIdRcMtiChHCJByuY8XK9",
- "tag": "u8kT0VAAtTswjGXxNpuX0g=="
}
}
Decrypt a message
Decrypt a message where the tenant manages the Keys for the recipientDidUrl
Authorizations:
Request Body schema: application/json
Decryption params
jwe required | string |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "jwe": "eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDp3ZWI6bWF0dHIuZ2xvYmFsI0V5MkN2V2N5MzQifQ.eyJtZXNzYWdlIjoidGVzdCJ9.dMvOGkfbRrjUJL7XYYAp1UxoHlt8J0N5_vRRLpTEHtQ4s8lwnMd0lhg7HiZVfvEyzk54f6J0CgTV5oHzVscdAA"
}
Response samples
- 200
- 400
{- "payload": "string",
- "senderDidUrl": "did:web:organization.com#2vcj3MjR4d",
- "senderPublicJwk": { },
- "recipientDidUrl": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d"
}
Send a message
Send an encrypted JWM format DIDComm message to a DID service endpoint.
In order to successfully route messages to their intended recipients the endpoint will resolve a public DID Document and look-up the service endpoint.
This endpoint only accepts Encrypted JWM payloads to ensure that messages sent for recipients are encrypted-at-rest whilst in messaging inboxes. The JWM should be encrypted for the recipient based on a key available in the DID Document.
Authorizations:
Request Body schema: application/json
to | string recipient DID |
string or object JWE message |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "to": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d",
- "message": {
- "protected": "eyJhbGciOiJYQzIwUCJ9",
- "recipients": [
- {
- "header": {
- "alg": "ECDH-1PU+A256KW",
- "kid": "did:key:z6MkgmEkNM32vyFeMXcQA7AfQDznu47qHCZpy2AYH2Dtdu1d#z6LSsvqSJkBvVEsDC8cxMHuQ3sKoLRMXB1MdtoLrMUq6A8Rg",
- "epk": {
- "kty": "OKP",
- "crv": "x25519",
- "x": "kYsO02jWHATTJel6OpePqlkdDmKlE5VOr18UblgL8W0"
}, - "skid": "did:key:z6Mko4PvuwKzmjtaKTEV6ZhMSYqX5myTSe3L3Md4feiwCoua#z6LSkKk8HK73jYfUQRBHX3Qeb1Agv39qVNFn7n2PjRvjpPcy"
}, - "encryption_key": "n1VUf5SQdSFNtb8DHzYfJJ_lFhJcGDAPJWG8Y1W3d2qYyPzyxMhyaA"
}, - {
- "header": {
- "alg": "ECDH-1PU+A256KW",
- "kid": "did:key:z6MkgxxdrThaRd7HbeAA4pYEwAgKT6ZXy2aNTcPkmeF1yWHN#z6LSgDiT1CkducmcSPaq9E1Uj1qdSXBjsUNqqLQLrUu8EHWd",
- "epk": {
- "kty": "OKP",
- "crv": "x25519",
- "x": "P3jcIMPGK8thxyHxUsWB5fEsLnltJqRDWMNywtexk24"
}, - "skid": "did:key:z6Mko4PvuwKzmjtaKTEV6ZhMSYqX5myTSe3L3Md4feiwCoua#z6LSkKk8HK73jYfUQRBHX3Qeb1Agv39qVNFn7n2PjRvjpPcy"
}, - "encryption_key": "5ZOTqwj8NredkXEOp4ZDLL1ohRQqNTS508BTkLlUVCkDoYvizCIdrg"
}
], - "ciphertext": "Dl4zBqMeEDwcnyyc17nYvSQ048fcsha_Lm0dfer1nqfo5y8oHvD2VGNTp_lawNJMWCzQF3NDZxxKFz__wTUeHCqisCE_DWbjo_W-R3avzW9S-JFajv9NRtjlfd5yp-1TtD2N5d-8oTtMGdAxq3dftN2Od1xRe4stubJBebl3nf8-lG99DIVGdL8Y-D98kFDxnMxgCKn4RXyHnMowFWlhQCooLeYqo8aWjqVFkzuJzn-p47W7rV9BCuoVThhVuNkjQm_dhBrqu0QMpjJucz7OvOHp0mojdYNKwvWT6dfOVNXetMlKjWCGtCTNFaDTGLc4agdcTjAlaF1iedcVXDOLqVvEugXWGlusE3a68y6gmPnqHjXR6CsEfPwkb5hKKtsyrh1eHu_9UUang5o6N76mummVw4UZkDF6tP1PVGPvyctz82tthnOcjO5mZQG41xfMEMNxWtF8P8wCh4LotpdexXtYigzBgkI1Qoa_FK1czYWAUovysAJCTOZtmg==",
- "iv": "jSd3E-ElCHE-QhSDxrQ-Jv4eQhkxOj0s",
- "tag": "dbDolGVDdvYsYdn-vVrICw=="
}
}
Response samples
- 400
{- "code": "string",
- "message": "string",
- "details": [
- {
- "value": "string",
- "msg": "Invalid value",
- "param": "id",
- "location": "body"
}
]
}
Create a webhook
Create a new webhook for this tenant.
The list of events
are the names of the events that will trigger the request to the designated url.
The url
entered is where the request will be sent.
Note: the URL has to have https://
as its prefix.
Authorizations:
Request Body schema: application/json
The webhook payload
events required | Array of strings List of events that cause the webhook to fire |
url required | string <uri> The destination url for the webhook |
disabled | boolean Whether or not the webhook is disabled |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "events": [
- "OidcIssuerCredentialIssued"
],
}
Response samples
- 201
- 400
{- "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
- "events": [
- "OidcIssuerCredentialIssued"
], - "disabled": false
}
Get a list of webhooks
Retrieve a list of webhooks for this tenant.
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
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/webhooks?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 400
{- "data": [
- {
- "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
- "events": [
- "OidcIssuerCredentialIssued"
], - "disabled": false
}, - {
- "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
- "events": [
- "OidcIssuerCredentialIssued"
], - "disabled": false
}
], - "nextCursor": "Y3JlYXRlZEF0PTIwMjItMDgtMjJUMDElM0E1OSUzQTE5LjYyMFomaWQ9MGMwOTk2MTEtMTljNC00ZjI5LTg3MjQtNmI5ZTViYTFlZjdj"
}
Get a webhook
Retrieve a specific webhook from this tenant.
Authorizations:
path Parameters
id required | string <uuid> Webhook ID Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/webhooks/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 400
{- "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
- "events": [
- "OidcIssuerCredentialIssued"
], - "disabled": false
}
Update a webhook
Update the following attributes on an existing webhook for this tenant.
events
an array of events that will trigger the webhook to the designated url.
url
for where the webhook will send the event payload.
disabled
that specifies whether or not the webhook will listen for events.
Authorizations:
path Parameters
id required | string <uuid> Webhook ID Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f |
Request Body schema: application/json
Update a Webhook
events required | Array of strings List of events that cause the webhook to fire |
url required | string <uri> The destination url for the webhook |
disabled | boolean Whether or not the webhook is disabled |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "events": [
- "OidcIssuerCredentialIssued"
], - "disabled": true
}
Response samples
- 200
- 400
- 404
{- "id": "0c099611-19c4-4f29-8724-6b9e5ba1ef7c",
- "events": [
- "OidcIssuerCredentialIssued"
], - "disabled": false
}
Remove a webhook
Removes a specific webhook from this tenant.
Authorizations:
path Parameters
id required | string <uuid> Webhook ID Example: 41458e5a-9092-40b7-9a26-d4eb43c5792f |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X DELETE \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/webhooks/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 400
- 404
{- "code": "BadRequest",
- "message": "Validation Error",
- "details": [
- {
- "location": "params",
- "msg": "Invalid value",
- "param": "webhookId",
- "value": "abc"
}
]
}
Get a list of webhook JWKs
Retrieve a list of webhook JWKs for this tenant.
Authorizations:
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/webhooks/jwks' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
{- "keys": [
- {
- "kty": "OKP",
- "crv": "Ed25519",
- "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo",
- "use": "sig",
- "kid": "FdFYFzERwC2uCBB46pZQi4GG85LujR8obt-KWRBICVQ"
}
]
}
Create a verifiable credential
Creates a Verifiable Credential (VC or just Credential) in a JSON-LD format adhering to the W3C VC Data Model spec.
Creating the Payload:
The values required by the operation are validated where available and used to construct the Verifiable Credential.
The Credential is issued using JSON-LD with linked data proofs, the type
values of the Credential and the Subject Claims must be represented by a schema in @context
.
The schema
https://www3.org/2018/credentials/v1
is always required in addition any@context
values, so that the Credential can be referenced.
The
type
value ofVerifiableCredential
must be used as the first value in the array to conform to the W3C VC Data Model spec.
Subject Identifiers
In general, the Subject identifier in the subjectId
field should have been authentically bound to the subject and authenticated against the information used in the claims, for example by using an OpenID Connect authentication flow or another mechanism including out-of-band processes.
Credentials may be issued without subject identifiers, this covers uses-cases, where the credential cannot or does not need to be adequately bound to a Subject DID and may be treated as a bearer credential or reissued at a later time once the credential can be bound.
ZKP-enabled BBS+ credential:
If you wish to issue a ZKP-enabled Verifiable Credential, the provided issuer
id
must be a did:key with a key type of bls12381g2
. The platform will automatically detect this capability and issue a ZKP-enabled BBS+ credential. Note that the schema https://w3c-ccg.github.io/ldp-bbs2020/context/v1
will automatically be added to the @context
in the credential.
During Preview this feature is experimental. It may change over time and may require credentials to be reissued.
Credential meta-data:
Setting the persist
value to true
will store the entire credential contents as well as the meta-data on the platform. If set to false
only the credential meta-data is held on the platform:
id
tag
(optional)credentialStatus
(optional)issuanceDate
The optional tag
value can be used to externally reference the issued credential.
Returns
On success, the Verifiable Credential is always provided in the response along with meta-data. Subject bound credential should be delivered to the intended subject.
Authorizations:
Request Body schema: application/json
The credential payload
name | string |
description | string |
@context required | Array of strings non-empty Additional to any JSON-LD contexts 'https://www.w3.org/2018/credentials/v1' is always required. |
subjectId | string non-empty Generally a DID, identifier of who/what the subject is |
tag | string [ 1 .. 1024 ] characters An optional tag to filter by, will not be part of the issued credential |
required | string or Array of strings Type for the Credential, VerifiableCredential must be presented |
claims required | object non-empty Each value is a claim that is defined by one of the JSON-LD schemas. |
required | object Includes Issuer id (DID), domain name and optional branding properties. |
object Includes optional credential branding properties. | |
persist | boolean Flag to indicate whether the full credential should be stored in platform |
revocable | boolean Flag to indicate if the credential needs to support revocation |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "name": "Alumni Credential",
- "description": "This credential shows that the person has attended the mentioned university.",
- "subjectId": "did:web:organization.com",
- "type": [
- "VerifiableCredential",
- "AlumniCredential"
], - "claims": {
- "givenName": "Jamie",
- "familyName": "Doe",
- "alumniOf": "Example University"
}, - "issuer": {
- "id": "did:web:organization.com",
- "name": "Example University"
}, - "persist": true,
- "tag": "identifier123",
- "revocable": true
}
Response samples
- 201
- 400
{- "id": "873277c0-a162-11ea-8a1d-a111119347e6",
- "credential": {
- "type": [
- "VerifiableCredential",
- "AlumniCredential"
], - "issuer": {
- "id": "did:web:organization.com",
- "name": "Example University"
}, - "issuanceDate": "2020-05-02T12:06:29.156Z",
- "credentialStatus": {
- "type": "RevocationList2020Status",
- "revocationListIndex": 1,
- "revocationListCredential": "https://tenant.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3"
}, - "credentialSubject": {
- "givenName": "Jamie",
- "familyName": "Doe",
- "alumniOf": "Example University"
}, - "proof": {
- "type": "Ed25519Signature2018",
- "created": "2020-05-02T12:06:29Z",
- "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "proofPurpose": "assertionMethod",
- "verificationMethod": "did:web:organization.com"
}, - "name": "Alumni Credential",
- "description": "This credential shows that the person has attended the mentioned university."
}, - "tag": "identifier123",
- "credentialStatus": {
- "type": "RevocationList2020Status",
- "revocationListIndex": 1,
- "revocationListCredential": "https://tenant.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3"
}, - "issuanceDate": "2020-05-02T12:06:29.156Z"
}
Retrieve list of credential data
Returns a list of all credential data stored in the tenant.
In the list
Inside the data
array, there is an body for each credential issued on the platform, in addition to the id
the body will contain optionally added meta-data and may contain the entire credential contents if persist
was invoked during credential creation.
Credentials issued via the OIDC Bridge are set not to be persisted.
Pagination
Pagination can be controlled by a cursor method using the cursor
and limit
query parameters. The nextCursor
is found at the start of each returned range of credential entries and the limit
determines how many entries are returned in that request, with a maximum value of 1000
.
Not using a query parameter defaults the response to return the first range of credential entries with a limit of 100.
The optional
tag
filter or the Credentialtype
can be used to retrieve credential data.
Authorizations:
query Parameters
tag | string The optional external reference to filter on Example: tag=identifier123 |
type | string The optional credential type to filter on Example: type=AlumniCredential |
limit | number [ 1 .. 1000 ] Range size of returned credential entries, default 100 Example: limit=2 |
cursor | string Starting point for the range of credential entries Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/credentials?tag=identifier123&type=AlumniCredential&limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 400
{- "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
- "data": [
- {
- "id": "873277c0-a162-11ea-8a1d-a111119347e6",
- "credential": {
- "type": [
- "VerifiableCredential",
- "AlumniCredential"
], - "issuer": {
- "id": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5",
}, - "issuanceDate": "2020-05-02T12:06:29.156Z",
- "credentialSubject": {
- "id": "did:key:z6Mkvji7zrwyFATXUzGNBSCnrPaZy7H3BWUnihrHvZdkEd9y",
- "givenName": "Jamie",
- "familyName": "Doe"
}, - "proof": {
- "type": "Ed25519Signature2018",
- "created": "2020-05-02T12:06:29Z",
- "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "proofPurpose": "assertionMethod",
- "verificationMethod": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5#z6Mkvji7zrwyFATXUzGNBSCnrPaZy7H3BWUnihrHvZdkEd9y"
}
}, - "tag": "identifier123",
- "issuanceDate": "2020-05-02T12:06:29.156Z"
}, - {
- "id": "9043aa74-eb08-11ea-adc1-0242ac120002",
- "tag": "identifier124",
- "credentialStatus": {
- "type": "RevocationList2020Status",
- "revocationListCredential": "https://tenant.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3",
- "revocationListIndex": 1
}, - "issuanceDate": "2020-10-06T03:21:02.397Z"
}
]
}
Retrieve credential data
Get data for a previously created credential using its ID.
In addition to the id
the body will contain optionally added meta-data and may contain the entire credential contents if persist
was invoked during credential creation.
Credentials issued via the OIDC Bridge do not have their contents persisted.
Authorizations:
path Parameters
id required | string Credential ID |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/credentials/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 400
- 404
{- "id": "873277c0-a162-11ea-8a1d-a111119347e6",
- "credential": {
- "type": [
- "VerifiableCredential",
- "AlumniCredential"
], - "issuer": {
- "id": "did:web:organization.com",
- "name": "Example University"
}, - "issuanceDate": "2020-05-02T12:06:29.156Z",
- "credentialStatus": {
- "type": "RevocationList2020Status",
- "revocationListCredential": "https://tenant.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3",
- "revocationListIndex": 4
}, - "credentialSubject": {
- "givenName": "Jamie",
- "familyName": "Doe"
}, - "proof": {
- "type": "Ed25519Signature2018",
- "created": "2020-05-02T12:06:29Z",
- "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "proofPurpose": "assertionMethod",
- "verificationMethod": "did:web:organization.com"
}
}, - "tag": "identifier123",
- "credentialStatus": {
- "type": "RevocationList2020Status",
- "revocationListCredential": "https://tenant.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3",
- "revocationListIndex": 4
}, - "issuanceDate": "2020-05-02T12:06:29.156Z"
}
Remove credential data
Remove all stored credential data from the tenant using its ID.
The entire entry including meta-data and the credential contents is removed from the system and cannot be recovered.
Authorizations:
path Parameters
id required | string Credential ID |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X DELETE \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/credentials/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 400
- 404
{- "code": "string",
- "message": "string",
- "details": [
- {
- "value": "string",
- "msg": "Invalid value",
- "param": "id",
- "location": "body"
}
]
}
Verify a credential
Send any JSON-LD Verifiable Credential that conforms to the W3C Verifiable Credentials data model to perform verification checks and return a response:
- 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 This endpoint can be used to check any Credential issued by any service provider.
Authorizations:
Request Body schema: application/json
object (VerifiableCredential) |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "credential": {
- "type": [
- "VerifiableCredential",
- "AlumniCredential"
], - "issuer": {
- "id": "did:web:organization.com",
- "name": "Example University"
}, - "issuanceDate": "2020-05-02T12:06:29.156Z",
- "credentialStatus": {
- "type": "RevocationList2020Status",
- "revocationListIndex": 1,
- "revocationListCredential": "https://tenant.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3"
}, - "credentialSubject": {
- "givenName": "Jamie",
- "familyName": "Doe"
}, - "proof": {
- "type": "Ed25519Signature2018",
- "created": "2020-05-02T12:06:29Z",
- "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "proofPurpose": "assertionMethod",
- "verificationMethod": "did:web:organization.com"
}, - "name": "Course credential",
- "description": "This credential shows that the person has attended the mention course and attained the relevant awards."
}
}
Response samples
- 200
{- "verified": true
}
Set credential revocation status
A credential can be revoked by setting the revocation status.
Authorizations:
path Parameters
id required | string <uuid> Credential ID Example: a80a5e7e-1972-4be6-8a4e-2adf09badf24 |
Request Body schema: application/json
Setting the revocation status
isRevoked required | boolean true if the credential is revoked, false otherwise |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "isRevoked": true
}
Response samples
- 404
{- "code": "NotFound",
- "message": "Validation Error",
- "details": [
- {
- "location": "path",
- "msg": "credential not revocable",
- "param": "id",
- "value": "a80a5e7e-1972-4be6-8a4e-2adf09badf24"
}
]
}
Retrieve credential revocation status
Retrieve the revocation status of a certain credential.
Returns
The revocation status of the credential
Authorizations:
path Parameters
id required | string <uuid> Credential ID Example: a80a5e7e-1972-4be6-8a4e-2adf09badf24 |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/credentials/:id/revocation-status' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 404
{- "isRevoked": false
}
Retrieve revocation list
Retrieve the revocation list that contains the revocation status of a number of credentials.
Returns
The revocation list
path Parameters
id required | string <uuid> Revocation list ID Example: cc641396-3750-43c8-b8b8-f30d74eb3fb3 |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/revocation-lists/:id'
Response samples
- 200
- 404
{- "type": [
- "VerifiableCredential",
- "RevocationList2020Credential"
], - "issuer": "did:web:organization.com",
- "issuanceDate": "2020-05-02T12:06:29.156Z",
- "credentialSubject": {
- "type": "RevocationList2020",
- "encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
}, - "proof": {
- "type": "Ed25519Signature2018",
- "created": "2020-05-02T12:06:29Z",
- "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "proofPurpose": "assertionMethod",
- "verificationMethod": "did:web:organization.com#CU6dJt9p8t"
}
}
Create a revocation message payload
Create a payload that can form a message in the JWM format that can be used in sending notifications to subjects based on the revocation status of their issued credentials.
- Use a DID setup on the tenant as the
from
value, this should be a DID with a key type suitable for messaging (not a BLS key type) - Include a SubjectDID as the
to
value - this value is only used in the message construction, it should be the same value as the intended recipient.
To send a notification to the Subject DID holder, use the payload with the /messaging/encrypt and /messaging/send endpoints.
Authorizations:
path Parameters
id required | string <uuid> Credential ID Example: 873277c0-a162-11ea-8a1d-a111119347e6 |
Request Body schema: application/json
Create a JWM message payload
from required | string non-empty DID on the tenant used in a message |
to required | Array of strings List of SubjectDIDs |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "from": "did:web:organization.com",
- "to": [
- "did:key:subjectDid1",
- "did:key:subjectDid2",
- "did:key:subjectDid3"
]
}
Response samples
- 201
{- "id": "string",
- "type": "string",
- "to": [
- "did:key:subjectDid1",
- "did:key:subjectDid2",
- "did:key:subjectDid3"
], - "from": "did:web:organization.com",
- "created_time": 0,
- "body": {
- "revocationListCredential": "string",
- "revocationListIndex": "string",
- "isRevoked": true
}
}
Create a presentation template
A Presentation Request Template defines which credentials are required for presentation. This is used to create the actual Presentation Request, which is used by the Mobile Wallet to select which credential it should display to the Holder, asking for confirmation to be used in the Presentation to be sent.
Creating the payload
The domain
value must always match the domain of the tenant being used.
The name
value is a convenience attribute for quickly determining the intended purpose of a created template.
The Presentation Request query
follows the Verifiable Presentation Request Specification.
The following query methods have been enabled:
- Query by Example
- Query by Frame
- DID Auth
Query can accept an array of types, which makes is possible to construct complex presentation requests from the template, however creating a valid Presentation Template does not ensure that logically valid Presentation Request is created or that a credential holder would be able to satisfy the request.
Query by Example
This is a basic form of requesting credential information, it is possible to limit the request based on:
- Credential Type - based on the
type
of the credential - Specific Trusted Issuer DIDs - an array of DIDs that the credential must have been issued by one of.
Query by Frame
Used primary for requesting specific claims from ZKP-enabled credentials, only the claims requested in the frame will be derived and sent in the presentation.
- Credential Type - If an array should match the exact
type
used in the Credential otherwise a string is required to beVerifiableCredential
. - CredentialSubject - request specific claims from a credential subject.
- Specific Trusted Issuer DIDs - an array of DIDs that the credential must have been issued by one of, ensure this DID is of a BLS key type that has issued a ZKP-enabled credential.
DID Auth
The type of Template will result in a DID Auth flow resulting in just the Subject DID from the holder to be provided in the response to the Presentation Request.
- DIDAuth
Returns
On Success, the response from the endpoint always include the Presentation Template ID, this UUID is required in OIDC Bridge Verifier instance setup and using the Verify using a Callback method. The Presentation Request endpoint uses this ID to determine the exact type of request message to create.
Authorizations:
Request Body schema: application/json
The template
domain required | string Must match domain of the tenant |
name required | string Internal descriptor only |
required | Array of CreatePresentationQueryByExample (object) or CreatePresentationQueryByFrame (object) or CreatePresentationDidAuthTemplate (object) |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "domain": "tenant.vii.mattr.global",
- "name": "alumni_credential_request",
- "query": [
- {
- "type": "QueryByExample",
- "credentialQuery": [
- {
- "required": true,
- "reason": "We need you to prove your alumni membership.",
- "example": {
- "type": "AlumniCredential",
- "trustedIssuer": [
- {
- "required": true,
- "issuer": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5"
}
]
}
}
]
}
]
}
Response samples
- 201
- 400
{- "id": "364b6a1b-3600-4927-a6ac-4d66aa6bbac3",
- "domain": "tenant.vii.mattr.global",
- "name": "alumni_credential_request",
- "query": [
- {
- "type": "QueryByExample",
- "credentialQuery": [
- {
- "required": true,
- "reason": "We need you to prove your alumni membership.",
- "example": {
- "type": "AlumniCredential",
- "trustedIssuer": [
- {
- "required": true,
- "issuer": "did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5"
}
]
}
}
]
}
]
}
Retrieve a list of presentation templates
Returns a list of all Presentation Templates on the tenant.
Use the name
value to determine the intended purpose of the templates.
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
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/presentations/templates?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
{- "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
- "data": [
- {
- "id": "64e45290-9980-11ea-b872-f1bee5fb328f",
- "domain": "tenant.vii.mattr.global",
- "name": "alumni_credential_request",
- "query": [
- {
- "type": "QueryByExample",
- "credentialQuery": [
- {
- "required": true,
- "reason": "string",
- "example": [
- { }
]
}
]
}
]
}
]
}
Retrieve a presentation template
Retrieve a Presentation Template by providing a template ID
Authorizations:
path Parameters
id required | string Presentation template ID |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/presentations/templates/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 400
- 404
{- "id": "64e45290-9980-11ea-b872-f1bee5fb328f",
- "domain": "tenant.vii.mattr.global",
- "name": "alumni_credential_request",
- "query": [
- {
- "type": "QueryByExample",
- "credentialQuery": [
- {
- "required": true,
- "reason": "string",
- "example": [
- {
- "@context": [
- null
], - "type": "AlumniCredential",
- "trustedIssuer": [
- { }
]
}
]
}
]
}
]
}
Delete presentation template
Delete a Presentation Template
Authorizations:
path Parameters
id required | string Presentation template ID |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X DELETE \ 'https://{tenant-subdomain}.vii.mattr.global/core/v1/presentations/templates/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 400
- 404
{- "code": "string",
- "message": "string",
- "details": [
- {
- "value": "string",
- "msg": "Invalid value",
- "param": "id",
- "location": "body"
}
]
}
Update presentation template
Update a Presentation Template using the template id
.
Follows the same structure as the Create a Presentation Template endpoint.
Authorizations:
path Parameters
id required | string Presentation template ID |
Request Body schema: application/json
id | string |
domain required | string Must match domain of the tenant |
name required | string Internal descriptor only |
required | Array of CreatePresentationQueryByExample (object) or CreatePresentationQueryByFrame (object) or CreatePresentationDidAuthTemplate (object) |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "id": "string",
- "domain": "string",
- "name": "string",
- "query": [
- {
- "type": "QueryByExample",
- "credentialQuery": [
- {
- "required": true,
- "reason": "string",
- "example": [
- {
- "@context": [
- null
], - "type": "AlumniCredential",
- "trustedIssuer": [
- { }
]
}
]
}
]
}
]
}
Response samples
- 200
{- "id": "64e45290-9980-11ea-b872-f1bee5fb328f",
- "domain": "tenant.vii.mattr.global",
- "name": "alumni_credential_request",
- "query": [
- {
- "type": "QueryByExample",
- "credentialQuery": [
- {
- "required": true,
- "reason": "string",
- "example": [
- {
- "@context": [
- null
], - "type": "AlumniCredential",
- "trustedIssuer": [
- { }
]
}
]
}
]
}
]
}
Create a presentation request
Creates a short lived Presentation Request.
Creating the payload
A challenge
can be used to correlate requests
The DID
is used a Verifier DID to prove the authenticity of the Request to holders
Any callbackUrl
provide will be called on receipt of the response to the Presentation Request.
If no expiresTime
is provided, a default of 5 minutes will be used.
Returns
The request
object holds the Presentation Request in the form of a constructed JWM message.
The request
needs to be signed and conveyed to the holder, using techniques like a QR, deeplink or encrypted and sent via a notification message.
Authorizations:
Request Body schema: application/json
The presentation request payload
challenge required | string Challenge can be used to match the response to a request |
did required | string DID of the Verifier.
You can find the DID from the following location within your DID document: |
templateId required | string ID of a |
expiresTime | number Unix timestamp in ms after which the request will be expired |
callbackUrl | string <uri> Endpoint that will receive the Verifiable Presentation |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "challenge": "64e45290-9980-11ea-b872-f1bee5fb328f",
- "did": "did:key:z6Mkt7bFYc4V2HdAxwhMtaY6cgJckYXwhYdPLJCcnVqzrkpr",
- "templateId": "64e45290-9980-11ea-b872-f1bee5fb328f",
- "expiresTime": 1592955632103,
}
Response samples
- 201
- 400
{- "id": "c74128a0-9949-11ea-9554-b5a630b3c119",
- "request": {
- "id": "c74128a0-9949-11ea-9554-b5a630b3c119",
- "from": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
- "created_time": 1606709582907,
- "expires_time": 2594859115000,
- "reply_to": [
- "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq"
], - "body": {
- "id": "64e45290-9980-11ea-b872-f1bee5fb328f",
- "domain": "tenant.vii.mattr.global",
- "name": "alumni_credential_request",
- "query": [
- {
- "type": "QueryByExample",
- "credentialQuery": [
- {
- "required": true,
- "reason": "string",
- "example": [
- { }
]
}
]
}
], - "challenge": "e1b35ae0-9e0e-11ea-9bbf-a387b27c9e60"
}
}
}
Create a presentation
Create a Verifiable Presentation on your tenant by providing one or more Verifiable Credentials.
To successfully create a Verifiable Presentation using this endpoint you must supply;
- a
holderDiDUrl
that is controlled by the tenant - a credentials collection containing only subject-bound credentials
- a credentials collection containing only credentials with a subject DID that is controlled by the tenant
The resulting Verifiable Presentation will contain a proof generated via the holder DID and each unique subject DID.
Non-subject-bound (bearer) credentials are not supported.
Authorizations:
Request Body schema: application/json
domain required | string |
holderDidUrl required | string <uri> |
Array of objects (VerifiableCredential) Array of credentials for W3C VC Presentation or ignore for DIDAuth | |
challenge required | string <uuid> |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "domain": "tenant.vii.mattr.global",
- "holderDidUrl": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
- "credentials": [
- {
- "type": [
- "VerifiableCredential",
- "AlumniCredential"
], - "issuer": {
- "id": "did:web:organization.com",
- "name": "Example University"
}, - "issuanceDate": "2020-05-02T12:06:29.156Z",
- "credentialStatus": {
- "type": "RevocationList2020Status",
- "revocationListIndex": 1,
- "revocationListCredential": "https://tenant.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3"
}, - "credentialSubject": {
- "givenName": "Jamie",
- "familyName": "Doe",
- "alumniOf": "Example University"
}, - "proof": {
- "type": "Ed25519Signature2018",
- "created": "2020-05-02T12:06:29Z",
- "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "proofPurpose": "assertionMethod",
- "verificationMethod": "did:web:organization.com"
}, - "name": "Alumni Credential",
- "description": "This credential shows that the person has attended the mentioned university."
}
], - "challenge": "e1b35ae0-9e0e-11ea-9bbf-a387b27c9e60"
}
Response samples
- 201
- 400
{- "presentation": {
- "@context": [
- { }
], - "type": [
- { }
], - "verifiableCredential": [
- {
- "type": [
- "VerifiableCredential",
- "AlumniCredential"
], - "issuer": {
- "id": "did:web:organization.com",
- "name": "Example University"
}, - "issuanceDate": "2020-05-02T12:06:29.156Z",
- "credentialStatus": {
- "type": "RevocationList2020Status",
- "revocationListIndex": 1,
- "revocationListCredential": "https://tenant.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3"
}, - "credentialSubject": {
- "givenName": "Jamie",
- "familyName": "Doe",
- "alumniOf": "Example University"
}, - "proof": {
- "type": "Ed25519Signature2018",
- "created": "2020-05-02T12:06:29Z",
- "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "proofPurpose": "assertionMethod",
- "verificationMethod": "did:web:organization.com"
}, - "name": "Alumni Credential",
- "description": "This credential shows that the person has attended the mentioned university."
}
], - "id": "string",
- "holder": "string",
- "proof": [
- {
- "type": "string",
- "created": "string",
- "challenge": "string",
- "domain": "string",
- "jws": "string",
- "proofPurpose": "string",
- "verificationMethod": "string"
}
]
}
}
Verify a presentation
Use this endpoint to verify a Verifiable Presentation that has been generated by any platform that adheres to the W3C Verifiable Credential Data Model.
Provide a presentation
in the Request
The platform will perform these checks:
Ensures the presentation conforms to the VC Data model
For each verifiableCredential
objects;
- Issuer DID can be resolved
- JSON-LD context is valid for subject claims
- Proof is valid & the credential has not been tampered with
- Is not in a revoked status on a RevocationList2020
- The proof is valid for each subjectDID to prove ownership Finally, a proof is valid for the holderDID for the Presentation
Response
If all checks are passed then the verified
boolean is true
Otherwise it returns false
with a basic reason
Further detailed reasons for verified false responses is a future roadmap item.
Authorizations:
Request Body schema: application/json
Presentation to verify
required | object |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "presentation": {
- "@context": [
- { }
], - "type": [
- { }
], - "verifiableCredential": [
- {
- "type": [
- "VerifiableCredential",
- "AlumniCredential"
], - "issuer": {
- "id": "did:web:organization.com",
- "name": "Example University"
}, - "issuanceDate": "2020-05-02T12:06:29.156Z",
- "credentialStatus": {
- "type": "RevocationList2020Status",
- "revocationListIndex": 1,
- "revocationListCredential": "https://tenant.vii.mattr.global/core/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3"
}, - "credentialSubject": {
- "givenName": "Jamie",
- "familyName": "Doe",
- "alumniOf": "Example University"
}, - "proof": {
- "type": "Ed25519Signature2018",
- "created": "2020-05-02T12:06:29Z",
- "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "proofPurpose": "assertionMethod",
- "verificationMethod": "did:web:organization.com"
}, - "name": "Alumni Credential",
- "description": "This credential shows that the person has attended the mentioned university."
}
], - "id": "string",
- "holder": "string",
- "proof": [
- {
- "type": "string",
- "created": "string",
- "challenge": "string",
- "domain": "string",
- "jws": "string",
- "proofPurpose": "string",
- "verificationMethod": "string"
}
]
}
}
Response samples
- 200
- 400
{- "verified": true
}
Convert linked-data documents
Convert a document like a JSON-LD Credential or a Verifiable Presentation into a CBOR-LD document, and vice versa.
This operation is in Technical Preview, you may experience some inconsistencies when converting linked-data documents between encoding formats and we may introduce breaking changes to this operation based on feedback.
The Convert operation can accept JSON-LD documents as an input and convert them to a CBOR-LD document represented in Base64. CBOR-LD documents can represent the same information in a smaller size that is more friendly for offline use-cases, such as embedding into a QR code printed onto physical media or a PDF.
Documents can also be converted from CBOR-LD in Base64 format to JSON-LD, the response can either be encoded in Base 64 or plain JSON. This is useful for accepting compressed Credentials or Verifiable Presentations and converting them for use on other operations like Verify a Credential or Verify a Presentation.
Wallet Presentations
The MATTR mobile wallet can create verifiable presentations from a single credential in a CBOR-LD format and encode this into a QR, a further layer of GZip compression is performed.
The MATTR Verify CBOR-LD Presentation sample app can be used as an example of how to verify these presentations using the MATTR VII APIs.
Limitations
Calculating the exact size of a credential/document that can be encoded into a QR and safely read by a camera is not straightforward. Larger credentials are unlikely to work, including those with embedded images (photos), large nested claims, or credentials with large signatures like BBS+, it is generally best to confirm by testing across a range of devices.
Deeply nested JSON-LD structures are currently unable to be converted to CBOR-LD due to limitations of the library, so it is possible to see errors.
We are aware that inline contexts may affect the performance for CBOR-LD compression. The Create Credential endpoint uses an inline @vocab
context, this may change in the future.
Authorizations:
Request Body schema: application/json
The request document data and options
required | object |
required | string or object |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "options": {
- "inputFormat": "jsonld",
- "outputFormat": "cborld",
- "outputEncoding": "base64"
}, - "data": {
- "@type": "Person",
- "name": "Jane Doe",
- "jobTitle": "Professor",
- "telephone": "(425) 123-4567",
}
}
Response samples
- 200
- 400
{- "metadata": {
- "encoding": "base64",
- "format": "cborld"
}, - "data": "2QUBpgBzaHR0cHM6Ly9zY2hlbWEub3JnLwIZBz4ZEJppUHJvZmVzc29yGRGSaEphbmUgRG9lGRUobig0MjUpIDEyMy00NTY3GRWsggFvd3d3LmphbmVkb2UuY29t"
}
Sign a Compact Credential
Create a Compact Credential by providing a valid payload.
The iss
contains the DID of the issuer, this must be a did:web using a P-256 key type available on the tenant.
The nbf
(not before), exp
(expiry) and iat
(issued at) are all dates expressed as a Unix timestamp in seconds that control the validity period of the credential once it has been issued.
aud
and sub
are optional fields in the credential.
The sub
attribute can be used if the credential only needs to contain a single claim, and that claim is unique and understood within the context of the issuer and the credential’s use.
Any additional claims to be represented by the credential should then be added in the payload object after the sub
attribute.
A separate option can be provided to specify if the credential should be revocable, this is false
by default.
Authorizations:
Request Body schema: application/json
Compact Credential payload to sign
required | object (CompactCredentialSignRequest) CompactCredentialSignRequest |
revocable | boolean Default: false |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "payload": {
- "iss": "did:web:organization.com",
- "nbf": 1645743759,
- "exp": 1646743759,
- "iat": 1645743759,
- "aud": "string",
- "sub": "string",
- "property1": "...",
- "property2": "..."
}, - "revocable": false
}
Response samples
- 200
{- "id": "string",
- "encoded": "CSC:/1/2KCE3IQEJB5DCMSLN5KWKZABE2QFQRVDAF4CIZDJMQ5HOZLCHIYDGOJUFUYTENJNGIZTOLJVGIWTCMJQFZXGO4TPNMXGS33ENZQW2ZLEJJXWQ3QH3BAFB3LISHKGQ2KBJ6Q35NXZFD6LGZ2YIAYHZAKCF7NKTIUZUTZQ3PWDBALAWVRG5XL2H4P4WFK25X3Y5X5RTN7NOZUST67KLCEFS3EPXQU5KM7VUGOPXJLQ6K5U676PMQNWRZCZ",
- "decoded": {
- "iss": "did:web:organization.com",
- "nbf": 1645743759,
- "exp": 1646743759,
- "iat": 1645743759,
- "jti": "6tVMmKodQNaLywW6NGA2aA",
- "property1": "...",
- "property2": "..."
}
}
Verify a compact credential
Verify a compact credential by sending the encoded payload and specifying options that could determine the resulting verification checks.
Standard checks performed on all verification requests:
- Conformance of the string and encoded data, all compact credentials must be pre-fixed with
csc/1
- Decode the CWT structure and validate attributes
- Fetch the public key from the
did.json
of the issuerdid:web
and validate the proof signature
Optional paramter checks:
trustedIssuers
if provided will compare theiss
field against the array of trusted issuers and only return verified if found in the array.assertNotBefore
is a Unix timestamp provided in seconds, verify will fail if the current time is before thenbf
valueassertNotAfter
is a Unix timestamp provided in seconds, verify will fail if the current time is after theexp
valuecheckRevocation
if the provided compact credential contains a revocation status list, this will be checked and verify will fail if the credential has been set to revoked
Authorizations:
Request Body schema: application/jsonapplication/jsonmultipart/form-data
payload required | string a compact credential encoded payload |
trustedIssuers | Array of strings |
assertNotBefore | boolean Default: true |
assertExpiry | boolean Default: true |
checkRevocation | boolean Default: true |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "payload": "CSC:/1/2KCE3IQEJB5DCMSLN5KWKZABE2QFQRVDAF4CIZDJMQ5HOZLCHIYDGOJUFUYTENJNGIZTOLJVGIWTCMJQFZXGO4TPNMXGS33ENZQW2ZLEJJXWQ3QH3BAFB3LISHKGQ2KBJ6Q35NXZFD6LGZ2YIAYHZAKCF7NKTIUZUTZQ3PWDBALAWVRG5XL2H4P4WFK25X3Y5X5RTN7NOZUST67KLCEFS3EPXQU5KM7VUGOPXJLQ6K5U676PMQNWRZCZ",
- "trustedIssuers": [
- "did:web:organization.com"
], - "assertNotBefore": true,
- "assertExpiry": true,
- "checkRevocation": true
}
Response samples
- 200
- 400
{- "verified": true,
- "decoded": {
- "iss": "did:web:organization.com",
- "nbf": 1645743759,
- "exp": 1646743759,
- "iat": 1645743759,
- "jti": "6tVMmKodQNaLywW6NGA2aA",
- "property1": "...",
- "property2": "..."
}, - "error": {
- "type": "string",
- "message": "string",
- "details": { }
}
}
Public revocation list discovery
Every revocable credential issued will reference a Revocation List, this is automatically created and held on the tenant for the Issuer.
The public revocation list endpoint can be obtained from the public revocation list discovery endpoint.
Authorizations:
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/v2/credentials/compact/revocation-lists' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
[- {
- "nextCursor": "string",
- "data": [
- {
- "id": "string",
- "issuer": "string",
- "url": "string"
}
]
}
]
Public revocation list
The public endpoint that retrieves the revocation list that contains the revocation status of a number of credentials.
Authorizations:
path Parameters
listId required | string ID of the revocation list |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/v2/credentials/compact/revocation-lists/:listId' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Update revocation status
A credential can be revoked by setting isRevoked to true. The status can be set back to false to reactivate the credential.
Authorizations:
path Parameters
id required | string Unique ID of the credential - JTI |
Request Body schema: application/json
Update revocation status
isRevoked required | boolean |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "isRevoked": true
}
Response samples
- 200
{- "id": "string",
- "isRevoked": true
}
Retrieve revocation status
Retrieve the revocation status of a credential.
Authorizations:
path Parameters
id required | string Unique ID of the credential - JTI |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/v2/credentials/compact/:id/revocation-status' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
{- "isRevoked": true
}
Generate a QR Code
Generate a QR Code to represent a Compact Credential from the base32
encoded string provided as the payload
and an optional width
.
- The maximum length of the payload is 3391 characters.
The width of the output QR code can be specified using the optional width
parameter.
- The maximum size of the width is 1000px. If not provided the QR code library will generate a QR code with optimised width based on the size of the payload in the request.
Authorizations:
Request Body schema: application/json
payload required | string String payload of the encoded compact credential |
width | number Width in pixels of the output png image |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "payload": "CSS:/1/2KCE3IQEJB5DCMSMGRKXI3IBE2QFSANKVACBUYQYB2HQKGTCDAHI6BQ2MIMA5DYBPAUWI2L...",
- "width": 0
}
Response samples
- 400
{- "code": "BadRequest",
- "message": "Validation Error",
- "details": [
- {
- "value": "1",
- "msg": "must be a string",
- "param": "payload",
- "location": "body"
}
]
}
List PDF Templates
Retrieves a list of all Compact Credential PDF templates available for use.
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
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/v2/credentials/compact/pdf/templates?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
{- "nextCursor": "0ecdcb57-ef2b-4aa1-be34-695c2d9d9486",
- "data": [
- {
- "id": "4eea7654-d4c5-4eba-bd7a-5ca334d54725",
- "name": "Certificate of participation",
- "fileName": "certificate_of_participation.pdf",
- "metadata": {
- "title": ""
}, - "fields": [
- {
- "key": "familyName",
- "value": "{{payload.sub_claims.familyName}}",
- "isRequired": true,
- "alternativeText": "Family Name",
- "fontName": "NZCPBaloo2"
}
]
}
]
}
Update PDF Template
Update a PDF template based on uploaded .zip archive data.
Authorizations:
path Parameters
id required | string PDF Template ID |
Request Body schema: application/zip
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X PUT \ 'https://{tenant-subdomain}.vii.mattr.global/v2/credentials/compact/pdf/templates/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>' \ -H 'Content-Type: application/zip'
Response samples
- 200
{- "id": "4eea7654-d4c5-4eba-bd7a-5ca334d54725",
- "name": "Certificate of participation",
- "fileName": "certificate_of_participation.pdf",
- "metadata": {
- "title": ""
}, - "fields": [
- {
- "key": "familyName",
- "value": "{{payload.sub_claims.familyName}}",
- "isRequired": true,
- "alternativeText": "Family Name",
- "fontName": "NZCPBaloo2"
}
]
}
Retrieve PDF Template
Retrieves a specific Compact Credential PDF template using its ID
Authorizations:
path Parameters
id required | string PDF Template ID |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/v2/credentials/compact/pdf/templates/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
{- "id": "4eea7654-d4c5-4eba-bd7a-5ca334d54725",
- "name": "Certificate of participation",
- "fileName": "certificate_of_participation.pdf",
- "metadata": {
- "title": ""
}, - "fields": [
- {
- "key": "familyName",
- "value": "{{payload.sub_claims.familyName}}",
- "isRequired": true,
- "alternativeText": "Family Name",
- "fontName": "NZCPBaloo2"
}
]
}
Remove PDF Template
Delete a PDF template by ID
Authorizations:
path Parameters
id required | string PDF Template ID |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X DELETE \ 'https://{tenant-subdomain}.vii.mattr.global/v2/credentials/compact/pdf/templates/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Generate compact credential PDF
Creates a PDF based on provided compact credential payload as the encoded string and selected template
Authorizations:
Request Body schema: application/json
The credential payload
templateId | string non-empty PDF Template identifier |
payload | string [ 1 .. 1024 ] characters Credential payload string |
Responses
Request samples
- Payload
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
{- "templateId": "4eea7654-d4c5-4eba-bd7a-5ca334d54725",
- "payload": "{payload}"
}
Create Apple Pass Template
Creates a custom Digital Pass template based on a composed .zip
file in the template
field.
Other form values are required to establish the connection to your Apple Developer account.
Apple Pass template uses the official Apple Pass bundle structure
├── icon.png
├── icon@2x.png
├── logo.png
├── logo@2x.png
└── pass.json
Authorizations:
Request Body schema: multipart/form-data
template required | string <binary> |
name required | string [ 1 .. 1024 ] characters Name of the template |
fileName required | string [ 1 .. 100 ] characters File name for generated .pkpass bundles, should only include alphanumeric characters, '_', or '-', and ends with '.pkpass'. |
teamIdentifier required | string Apple team identifier |
passTypeIdentifier required | string Apple pass identifier |
wwdr required | string Apple G1 or G4 WorldWide Developer Relations certificate |
signerCert required | string Apple Pass signer certificate |
signerKey required | string The encrypted key of the Apple Pass signer certificate |
signerKeyPassphrase required | string Passphrase for the encrypted signer certificate key |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X POST \ 'https://{tenant-subdomain}.vii.mattr.global/v2/credentials/compact/digitalpass/apple/templates' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>' \ -H 'Content-Type: multipart/form-data' \ -F fileName=certificate_of_participation.pkpass \ -F 'name=Certificate of participation' \ -F passTypeIdentifier=pass.myproject.participation.pk \ -F signerCert=string \ -F signerKey=string \ -F signerKeyPassphrase=string \ -F teamIdentifier=GH5P43ABC \ -F template=string \ -F wwdr=string
Response samples
- 201
- 400
{- "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
- "passType": "apple",
- "name": "Certificate of participation",
- "metadata": {
- "fileName": "certificate_of_participation.pkpass",
- "teamIdentifier": "GH5P43ABC",
- "passTypeIdentifier": "pass.myproject.participation.pk"
}
}
List Apple Pass Templates
Retrieves a list of all Digital Pass template available for use.
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
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X GET \ 'https://{tenant-subdomain}.vii.mattr.global/v2/credentials/compact/digitalpass/apple/templates?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
- 200
- 400
{- "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h",
- "data": [
- {
- "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
- "passType": "apple",
- "name": "Certificate of participation",
- "metadata": {
- "fileName": "certificate_of_participation.pkpass",
- "teamIdentifier": "GH5P43ABC",
- "passTypeIdentifier": "pass.myproject.participation.pk"
}
}
]
}
Update Apple Pass Template
Update an Apple Pass template based on the uploaded .zip archive data.
Authorizations:
path Parameters
id required | string Digital Pass Template ID |
Request Body schema: multipart/form-data
template required | string <binary> |
name required | string [ 1 .. 1024 ] characters Name of the template |
fileName required | string [ 1 .. 100 ] characters File name for generated .pkpass bundles, should only include alphanumeric characters, '_', or '-', and ends with '.pkpass'. |
teamIdentifier required | string Apple team identifier |
passTypeIdentifier required | string Apple pass identifier |
wwdr required | string Apple G1 or G4 WorldWide Developer Relations certificate |
signerCert required | string Apple Pass signer certificate |
signerKey required | string The encrypted key of the Apple Pass signer certificate |
signerKeyPassphrase required | string Passphrase for the encrypted signer certificate key |
Responses
Request samples
- curl
- Node.js
- JavaScript
- Python
- C#
- Java
curl -i -X PUT \ 'https://{tenant-subdomain}.vii.mattr.global/v2/credentials/compact/digitalpass/apple/templates/:id' \ -H 'Authorization: Bearer <YOUR_JWT_HERE>' \ -H 'Content-Type: multipart/form-data' \ -F fileName=certificate_of_participation.pkpass \ -F 'name=Certificate of participation' \ -F passTypeIdentifier=pass.myproject.participation.pk \ -F signerCert=string \ -F signerKey=string \ -F signerKeyPassphrase=string \ -F teamIdentifier=GH5P43ABC \ -F template=string \ -F wwdr=string
Response samples
- 200
- 400
- 404
{- "id": "3812166c-ac9f-4e4e-96dd-c1336b5be378",
- "passType": "apple",
- "name": "Certificate of participation",
- "metadata": {
- "fileName": "certificate_of_participation.pkpass",
- "teamIdentifier": "GH5P43ABC",
- "passTypeIdentifier": "pass.myproject.participation.pk"
}
}