How to configure a custom domain

Custom domains represent your known and trusted brand, and can assist in instilling trust with your end-users when they interact with your MATTR VII tenant.

Prerequisites

You must have an existing web domain.
You must have control over this web domain DNS records.
You must have a web service that runs on your web domain and can redirect or proxy requests.

Overview

Configuring a custom domain for your MATTR VII tenant comprises the following steps:

Create custom domain configuration

Request

Make a request of the following structure to configure your custom domain:

HTTP

POST /v1/config/domain

JSON

{
    "name": "Custom Site",
    "logoUrl": "https://my-custom.site/logo-social.png",
    "domain": "my-custom.site"
}

name : Insert a name for the custom domain that will be displayed to digital wallet holders when they receive credential offers or verification requests from your MATTR VII tenant.
logoUrl : Insert a URL for a logo that will be displayed to digital wallet holders when they receive credential offers or verification requests from your MATTR VII tenant:
- URL must be publicly available.
- Must be a square image.
- png and jpg files are supported.
- Recommended size is 64x64 px.
- Recommended maximum size is 15 KB.
domain : Insert the full custom domain, leaving out the protocol (e.g. https://).

Response

JSON

{
    "name": "Custom Site",
    "logoUrl": "https://my-custom.site/logo.png",
    "domain": "my-custom.site",
    "verificationToken": "a45ba33b-6c47-4349-7d49-a516c4d38406",
    "isVerified": false
}

verificationToken : This value must be added to your domain DNS entry TXT record in step 2.
isVerified : This will indicate false until the domain has been verified as described in step 3. MATTR VII will only use the custom domain after it has been verified and this field indicates true.

Once the configuration is created, it is added to your tenant's manifest.json file. This is one of the files you will need to create redirects to.

Insert verification token into custom domain TXT record

Insert the verificationToken (obtained in step 1) into a TXT record in your custom domain DNS entry.

⚠️

This TXT record must exist on the domain indefinitely while using the MATTR VII platform.

The exact steps to perform this will vary depending on your DNS service provider:

Troubleshooting

If you can't set a TXT record for your custom domain because it already has a CNAME record, you can workaround this issue by performing the following:

Remove the CNAME record.
Add a TXT record with the correct verificationToken.
Verify your custom domain.
Remove the TXT record.
Return the CNAME record.

Verify custom domain

Once your DNS provider has registered your TXT value and the change has been propagated, MATTR VII must reach out to the public DNS record and confirm the value matches the one set up on your tenant.

Request

Make a request of the following structure to verify your custom domain:

HTTP

POST /v1/config/domain/verify

Response

204 : (with no body): Verification successful! Your custom domain is now active!
400 : Something has gone wrong with the DNS setup. It could be that you need to wait longer to ensure your TXT record has propagated or repeat the process to verify domain ownership.
404 : No custom domain configured on the tenant. Return to step 1 and configure a custom domain.

Create redirects for required assets

For your custom domain to function properly, you will need to setup redirects to assets that are hosted on your MATTR VII tenant. Different redirect are required based on features used as part of your implementation:

Asset path	Description	Required
/manifest.json	This file is required to provide digital wallet clients with information about your custom domain, such as its name and logo image.	Always
/.well-known/did.json	This is the did:web associated with your domain. It must be available for your did:web to be resolvable.	Only when issuing Compact and/or Web Credentials
/.well-known/did-configuration	This file is used to establish trust in the DID to domain linkage. This will ensure any digital wallet clients can resolve DIDs from your custom domain and verify the DID-to-domain linkage.	Only when issuing Compact and/or Web Credentials
/.well-known/openid-credential-issuer	This file includes details required for interacting with your tenant as part of an OID4VCI workflow.	Only when issuing credentials using the OID4VCI workflow

For example, if we were to set up mattr.global as a custom domain for the Learn MATTR VII tenant, we would need to create the following redirect for /manifest.json :

Origin	Redirect target
`https://mattr.global/manifest.json`	`https://learn.vii.au01.mattr.global/manifest.json`

Once this redirect is setup, users attempting to interact with the custom domain will be served the asset from the Learn MATTR VII tenant.

If any of the redirect paths are already used by your main website, you may need to create a separate subdomain for your MATTR VII custom domain.

Retrieve an access token Query analytic events