Custom domain

You can configure a custom domain for your MATTR VII tenant to represent your brand and instil trust with your end-users. For example, end-users might not feel comfortable claiming a credential issued from your MATTR VII tenant URL (e.g. https://learn.vii.au01.mattr.global), as they don’t know who or what MATTR is. Using your own domain might be a better approach.

Custom domains don’t change how you interact with your tenant for administration functions and don’t prevent the existing tenant domain from being accessed.

Since MATTR VII tenants are not exposed to end-users directly, the custom domains model we have implemented does not require full DNS mapping of a custom domain to a tenant (i.e. CNAME or A record). Instead, we allow setting a custom domain and then proving ownership using a TXT record on the DNS record.

Where your custom domain appears

Once your custom domain is verified, MATTR VII uses it in place of your tenant URL wherever your tenant identifies itself to an external party, such as a digital wallet or a relying party. It does not replace the URLs that serve traffic. Your tenant URL continues to host every API endpoint, including the endpoints wallets call during issuance and verification.

Have your redirects in place before your custom domain goes live. Once MATTR VII starts publishing the domain, every path in the custom domain guide that applies to your implementation must resolve from it, otherwise wallets and relying parties cannot retrieve your metadata. If your DNS provider has long lead times, prepare the redirects on your web service first, then complete verification.

Digital wallet display

The name and logo you set in your custom domain configuration are published in your tenant's manifest.json file. Publishing that file is a MATTR VII convention rather than something any wallet specification defines, so reading it is optional. A wallet only surfaces your branding if it has been built to fetch manifest.json from your domain. MATTR's wallets do, and display those values as the brand behind your tenant when a holder claims a credential or responds to a presentation request. Assume any other wallet ignores the file unless its vendor tells you otherwise.

Credential offers and issuance metadata

In OID4VCI issuance flows, your custom domain becomes the issuer identifier that wallets see:

The authorization, token, credential, and JWKS endpoints published in that metadata continue to point at your tenant URL, so wallets still exchange requests with your tenant directly.

Two consequences are worth calling out for anyone building a wallet against your tenant. Because the issuer identifier changes, the proof of possession JWT sent to the credential endpoint must carry your custom domain in its aud claim. A proof addressed to your tenant URL is rejected as an invalid audience. The access tokens your tenant issues are also bound to the custom domain, which becomes the iss and aud of the token and the resource it is scoped to.

mDocs online verification

In remote verification flows, the OpenID4VP authorization request your tenant signs uses your custom domain as the client_id, paired with the x509_san_dns client identifier scheme. MATTR VII signs that request with your verification request signer certificate and passes the certificate in the x5c header of the signed request object. Your custom domain appears in that certificate as a DNS subject alternative name, and a wallet following OpenID for Verifiable Presentations 1.0, section 5.9, checks the two against each other. The same domain is used as the client identifier in the session transcript that the holder's device signs over, so a wallet that presents a different value fails device authentication.

MATTR VII also publishes your verifier metadata at https://your-custom-domain/.well-known/oauth-client, and includes the same metadata inline as the client_metadata parameter of the signed request. MATTR's own wallet implementation fetches the published document and verifies the request signature against the keys listed there, so that redirect must be live before you can run a remote verification against it. OpenID for Verifiable Presentations expects a wallet to take verifier metadata other than the public key from client_metadata, so treat the fetch as MATTR wallet behavior rather than something every wallet does.

Either way, your verifier certificates must carry your custom domain rather than your tenant URL. If MATTR VII generates them for you this happens automatically. If you upload a signer certificate signed by your own CA, MATTR VII rejects it unless it carries a DNS:your-custom-domain subject alternative name.

Certificates

MATTR VII writes your custom domain into the certificates it generates for you. It always appears in the default subject common name, and, for the certificate types that carry alternative names, in the subject and issuer alternative names:

Where the API accepts a common name of your own, your value is used instead. That applies to the IACA, the document signer certificate, the verifier root CA, the wallet attestation root CA, and the DTS root CA. Certificate signing requests that you send to an external CA carry a timestamp appended to the common name, so that repeated requests do not clash at the CA, and the verification request signer is named your-custom-domain Verifier Signer <timestamp> on that path rather than your-custom-domain Reader Authentication.

Alternative names vary by certificate type. The document signer certificate and the status list signer certificate carry your custom domain as both a subject and an issuer alternative name, in the form https://your-custom-domain. The IACA and the verifier root CA carry it as an issuer alternative name only. The verification request signer carries two subject alternative names, the URI https://your-custom-domain and the bare DNS name your-custom-domain, and it is the DNS name that a wallet matches against the client_id. The wallet attestation and DTS certificates do not carry alternative names.

Certificate revocation lists are an exception to this. Their distribution URLs always point at your tenant URL, so they do not need a redirect.

Status list URLs

Status lists work the same way. Every mDoc your tenant issues carries the URL where a verifier retrieves its revocation status, and that URL always uses your tenant URL, whether or not a custom domain is configured:

https://your-tenant-url/v2/credentials/mobile/status-lists/{statusListId}/token

The status list distribution endpoint published in your issuer metadata and written into your IACA behaves the same way. Because these URLs are fixed at the time a credential or certificate is created, keeping them on your tenant URL means verifying an already issued mDoc never depends on your custom domain, and changing your custom domain later has no effect on credentials you have already issued.

Requirements

• Any MATTR VII tenant can only be linked to one custom domain.
• You must be on a MATTR VII paid plan.
• 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.

Process overview

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

1. Configure a custom domain.
2. Verify domain ownership.
3. Verify your custom domain.
4. Create required redirects.