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.

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

Retrieve the custom domain information and it's verification status for your Mattr VII tenant.

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.

Update the custom domain.

Follows the same structure as the Create a Custom Domain endpoint.

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

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.

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 from PROCESSING to COMPLETED once publicly resolvable.
• localMetadata: This includes the initial DID document that the platform expects to find publicly resolvable.

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.

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.

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

An inbox will hold messages for DIDs that are registered with the inbox

Returns a list of all registered inboxes for the tenant

Returns a single inbox based on the Inbox ID

Update the inbox configurations

Deletes a specific inbox

This endpoint is responsible for registering DIDs to a specific Inbox. Currently, DID registration with inboxes is limited to did:key

Returns a list of all DIDs for the specific Inbox

Unregister a DID from a specific inbox

List of inbox messages

Returns an inbox message

Deletes an inbox 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

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.

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

Decrypt a message where the tenant manages the Keys for the recipientDidUrl

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.

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.

Retrieve a list of webhooks for this tenant.

Retrieve a specific webhook from this tenant.

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.

Removes a specific webhook from this tenant.

Retrieve a list of webhook JWKs for this tenant.

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 of VerifiableCredential 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.