Learn

Configure a custom domain

Prerequisites

  • You must be on a MATTR VII paid plan. Get in touch to learn more.

  • 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.

Request

Make the following request to configure your custom domain:

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/core/v1/config/domain
json
Copy to clipboard.
1{
2  "name": "Custom Site",
3  "logoUrl": "https://my-custom.site/logo-social.png",
4  "domain": "my-custom.site"
5}

  • 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.

    • Recommended size is 64x64 px.

    • png and jpg files are supported.

    • The recommended maximum size is 15 KB.

  • domain: Insert the full custom domain, leaving out the protocol (e.g. https://).

Response

json
Copy to clipboard.
1{
2  "name": "Custom Site",
3  "logoUrl": "https://my-custom.site/logo.png",
4  "domain": "my-custom.site",
5  "verificationToken": "a45ba33b-6c47-4349-7d49-a516c4d38406",
6  "isVerified": false
7}

  • verificationToken: This value must be added to your domain DNS entry TXT record. Refer to Verify domain ownership for more information.

  • isVerified: This will indicate false until the domain has been verified. MATTR VII will only use the custom domain after it has been verified and this field indicates true.

Where should I host?

You may choose to create a separate subdomain from your main web presence to expose to end-users as part of managing their digital identities, or you may choose to run from your existing main website. The choice may come down to practical implementation details as you will need to setup redirects to certain paths:

bash
Copy to clipboard.
1/.well-known/did-configuration
2/.well-known/did.json
3/manifest.json
4/.well-known/openid-credential-issuer

If these paths are already or likely to be used by your main website, you may want to consider using them under a subdomain.

What's next?

Now that you have configured your custom domain, you can progress to verify domain ownership over your custom domain.