Credential configurations
Credential configurations are templates that define rules and parameters that are used to issue a specific type of digital credential. They are referenced in Credential offers and define rules and parameters that control the structure and content of the credentials being issued.
Once you create a credential configuration, its details are available on your tenant’s
./well-known/openid-credential-issuer endpoint
(https://{your_tenant_url}/.well-known/openid-credential-issuer) so that credentials available
from an issuer can be looked up by a wallet. If this endpoint is not resolvable, OID4VCI workflows
would fail. This is especially important when configuring a
Custom domain, which requires creating a redirect from your
custom domain URL to your MATTR VII tenant URL where this resource is available.
Every MATTR VII tenant can include multiple Credential configurations to meet different use cases.
Key considerations
When creating a new credential configuration, an issuer should take the following factors into account:
- Credential type: Used to uniquely identify credentials issued via this configuration.
- Credential content: Decide what information will be included in the credential, and how it will be structured.
- Credential validity: Set the appropriate validity period to reflect how long the credential should be considered accurate and trustworthy.
- Revocation support: Determine whether the credential needs to support revocation status updates.
- Branding configuration: Specify how the credential should appear in a digital wallet. While display conventions are not yet standardized, MATTR issuance and holding capabilities implement a proprietary format to support branding, clarity, and holder trust.
Credential type
The credential type is used to differentiate between different types of credentials. It is a unique identifier that specifies the purpose and structure of the credential being issued. For example:
UniversityDegreeCredential: Indicates that the credential being issued is a university degree certificate.EmployeeIDCredential: Indicates that the credential being issued is an employee ID card.VaccinationCertificate: Indicates that the credential being issued is a vaccination record.
Some credential types are standardized and widely recognized, such as:
org.iso.18013.5.*.mDL: Indicates that the credential being issued is a mobile driving license (mDL) compliant with the ISO/IEC 18013-5:2021 standard.
Some MATTR VII issuance logic is based on the set credential type. For example, when set to
org.iso.18013.5.*.mDL (where * is a positive integer), MATTR VII recognizes that this is an
attempt to create an mDL credential configuration and will fail if the validity period is set to 427
days or more to comply with ISO/IEC 18013-5:2021.
Best Practices
To comply with the emerging ISO/IEC TS 23220 requirements, credential types must be named using a reverse domain name that is under the control of the type designer. For example:
com.example.credentialtype.1
This approach is necessary because registration in the ISO/IEC 23220-7 type registry requires proof of domain ownership.
It is also recommended to include a version identifier (e.g., .1, .2) at the end of the credential type name. This makes it possible to introduce new versions without breaking compatibility and ensures it is always clear which version of the type is being referenced.
Credential content
The credential content defines the specific information that will be included in the credential, commonly referred to as claims. These claims can include various details about the credential holder such as their name, email address, and any other relevant data.
Namespaces
Namespaces provide a structured way to organize claims within a credential. They act like containers or “labels” that group related claims together, ensuring that their meaning is unambiguous and consistent across different contexts. Using namespaces helps avoid confusion when similar claims appear in different credential types, and it enables reuse of standard definitions across multiple contexts.
For instance, both a university credential and a driver’s license might include a claim called
issue_date, but the meaning differs — in the university context it refers to when the student ID
was issued, while in the driver’s license it refers to when the license was granted. By grouping
these under separate namespaces (org.example.university.1.issue_date vs.
org.example.driverslicense.1.issue_date), each claim is clearly contextualized, avoiding confusion
while still allowing both credentials to coexist in the same ecosystem.
claimMappings can be defined in two ways:
- Flat namespace: All claims are expressed at the same level.
- Multiple/grouped namespaces: Claims are grouped into structured objects under different namespaces.
For example, the ISO/IEC 18013-5 specification for mobile Driving Licenses (mDLs) defines a standard
org.iso.18013.5.1 namespace that covers a wide set of claims such as family_name, given_name,
birth_date, and portrait. This namespace is not exclusive to driver licenses. It can be reused
across other mDoc types, such as a mobile ID (mID) or a residence permit, which also need to
represent personal identity attributes.
Regardless of the approach, the semantics of common claims must remain unchanged. For example,
first_name should always refer to the credential holder’s first name. Any additional claims should
be clearly named or placed under an appropriate namespace to prevent ambiguity.
The following examples illustrate both approaches:
Best Practices
- It is recommended to append a version identifier (e.g., .1, .2) to namespaces (similar to credential types). This allows new versions of a namespace to be introduced without breaking interoperability and makes it clear which revision a given namespace belongs to.
- Using multiple namespaces may introduce a small binary size overhead, but it provides better scalability. This is particularly useful when the same namespace is reused across different credential types. Reusing namespaces ensures consistency in meaning while avoiding duplication.
ISO/IEC TS 23220-2 namespace and claims
SO/IEC TS 23220-2:2024 is a Technical Specification that defines reusable namespaces and claims. A second edition is currently under development and is expected to be published soon. If compliance with ISO/IEC TS 23220-2:2024 is desired, the reusable namespace and claims can be adopted. Reusing these common namespace and claims helps ensure semantic consistency.
The example below illustrates how to reference the ISO/IEC TS 23220-2:2024 namespace and claims in a credential configuration. This example includes all the claims defined in the standard, but in practice you would typically select only the claims that are relevant to your use case:
{
"claimMappings": {
"org.iso.23220.1": {
"family_name_unicode": {
// Last name, surname, or primary identifier of the holder (unicode characters)
"type": "string"
},
"given_name_unicode": {
// First name(s), other name(s), or secondary identifier of the holder
"type": "string"
},
"sex": {
// Holder's sex using values as defined in ISO/IEC 5218 (0=Unknown, 1=Male, 2=Female, 9=Not applicable)
"type": "number"
},
"height": {
// Holder's height in centimetres (uint)
"type": "number"
},
"weight": {
// Holder's weight in kilograms (uint)
"type": "number"
},
"birthplace": {
// Country and municipality or state/province where the holder was born
"type": "string"
},
"resident_address_unicode": {
// The place where the holder resides and/or may be contacted (street/house number, municipality etc.)
"type": "string"
},
"resident_city_unicode": {
// The city/municipality (or equivalent) where the holder lives
"type": "string"
},
"resident_postal_code": {
// The postal code of the holder
"type": "string"
},
"resident_country": {
// The country where the holder lives as a two letter country code
// (alpha-2 code) defined in ISO 3166-1
"type": "string"
},
"biometric_template_face": {
// A reproduction of the holder’s portrait
"type": "binary"
},
"portrait": {
// Portrait data as specified in ISO/IEC 18013-2:2020, Annex D,
// but only JPEG or JPEG2000 shall be supported.
"type": "binary"
},
"portrait_capture_date": {
// Date when portrait was taken
"type": "date"
},
"fingerprint": {
// A reproduction of the holder’s fingerprint data (TBC)
"type": "binary"
},
"nationality": {
// Nationality of the holder as two letter country code (alpha-2 code)
// or three letter code (alpha-3 code) defined in ISO 3166-1b
"type": "string"
},
"business_name_unicode": {
// Business name of the holder
"type": "string"
},
"organization_name_unicode": {
// Name of the legal person
"type": "string"
},
"name_at_birth": {
// The name(s) which holder was born
"type": "string"
},
"telephone_number": {
// Telephone number of the holder, including country code
// as specified ITU-T E.123 and ITU-T E.164
"type": "string"
},
"email_address": {
// E-mail address of the holder
"type": "string"
},
"profession": {
// Profession of the holder
"type": "string"
},
"title": {
// Academic title of the holder
"type": "string"
},
"age_in_years": {
// The age of the holder
"type": "number"
},
"age_birth_year": {
// The year the holder was born
"type": "number"
},
"age_over_NN": {
// e.g., age_over_18, age_over_21
"type": "boolean"
},
"issuing_country": {
// Country code as alpha 2 and alpha 3 code, defined in ISO 3166-1,
// which issued the credential or within which the issuing
// authority is located
"type": "string"
},
"issuing_subdivision": {
// Subdivision code as defined in ISO 3166-2, which issued
// the credential or within which the issuing authority located
"type": "string"
},
"issuing_authority_unicode": {
// Name of issuing authority
"type": "string"
},
"issue_date": {
// Date the credential was issued
"type": "date"
},
"expiry_date": {
// Date the credential expires
"type": "date"
},
"document_type": {
// The document type
"type": "string"
},
"document_number": {
// The number assigned or calculated by the issuing authority
"type": "string"
}
}
}
// Rest of the credential configuration
}MATTR VII does not currently support the ISO/IEC TS 23220-2:2024 birthdate claim.
Claims mapping
Credential configurations control the structure and content of issued credentials by defining the
mapping of claims from an internal user object into the issued credential. The user object is
populated during the OID4VCI workflow and contains information about the user that is being issued a
credential. This information can come from various sources:
- In an Authorization Code flow these can be retrieved from the configured Authentication provider and/or Interaction hook.
- In a Pre-authorized Code flow these can be provided directly in the credential offer by the issuer.
- In either flow a compatible Claims source can be configured to provide additional user attributes.
This is an example of what a user object looks like:
{
"authenticationProvider": {
"url": "https://account.example.com",
"subjectId": "145214ad-3635-4aff-b51d-61d69a3c8eee"
},
"claims": {
"given_name": "John",
"family_name": "Doe",
"email": "john.doe@example.com",
"address": {
"formatted": "123FooRd,BarWorld"
}
}
}authenticationProvider(only provided for users in an Authorization Code flow) : This object containsurl: References the Authentication provider that is used to authenticate this user.subjectId: Indicates the unique identifier of the user with this Authentication provider.
claims: This object is used to hold claims fetched as part of the OID4VCI workflow. The claims object can contain simple key-value pairs (e.g.,given_name,family_name,email) or nested objects (e.g.,address).
The actual mapping from the user object into the issued credential is defined in the claimMapping
object in the credential configuration. Each item in the object represents a credential claim and
can be mapped in different ways, depending on the use case.
Here is an example of a claimMapping object:
{
"claimMappings": {
"dateOfBirth": {
"mapFrom": "claims.dateOfBirth",
"required": true,
"type": "string"
},
"email": {
"mapFrom": "claims.email",
"required": false,
"defaultValue": "Not available",
"type": "string"
}
}
}mapFrom: This is used to map a claim in the issued credential to a specific attribute in the claims object. In this example, thedateOfBirthclaim in the issued credential is mapped directly fromclaims.dateOfBirthin the user object, and theemailclaim is mapped fromclaims.email.type: This defines the data type of the claim. Refer to the API Reference for available types and their usage. In this example, bothdateOfBirthandemailare defined as strings.required: When set totrue, the claim must be provided during issuance. If it is not provided and notdefaultValueis set, issuance will fail. If set tofalseor not present, the claim is optional and issuance will succeed even if the claim is not provided. In this example,dateOfBirthis a required claim, whileemailis optional.defaultValue: This is used to set a default value for the claim if it is not provided during issuance. This is useful for optional claims where a sensible default can be applied. In this example,Not availableis set as the default value for theemailclaim.
The following logic applies to combining these properties:
- Either
mapFromordefaultValuemust be provided for each claim. - If
mapFromis provided and the claim is found in theuserobject, its value will be used. - If
mapFromis provided but the claim is not found in theuserobject:- If
requiredistrueand nodefaultValueis provided, issuance will fail. - If
requiredisfalseor not present and adefaultValueis provided, thedefaultValuewill be used. - If
requiredisfalseor not present and nodefaultValueis provided, the claim will be omitted from the issued credential.
- If
- If only
defaultValueis provided (withoutmapFrom), the claim will always be set to thedefaultValue.
Credential validity
Credential validity defines the period during which the credential is considered valid and can be used for its intended purpose. Invalid credentials would fail verification by any standards compliant relying party/verifier.
The credential validity can be set using a combination of three properties in the credential configuration:
- Relative validity:
expiresIn: Determines when will the credential expire in relation to its issuance time and date.
- Absolute validity:
validFrom: Specifies an absolute date and time from which the credential is considered valid. For example, a credential could become valid on a fixed date, regardless of when it is issued.validUntil: Specifies an absolute date and time at which the credential expires. For example, a credential could be valid until a fixed date, regardless of when it is issued.
Absolute validity using validFrom and/or validUntil is only supported in OID4VCI
Pre-authorized Code flows.
Here are two examples of how these properties can be used:
The following rules apply when setting these properties:
expiresInmust be provided.- If
expiresInis set andvalidUntilis not provided, the expiration date and time will be calculated by adding theexpiresInduration to the issuance date and time. - If
validUntilis provided, it takes precedence overexpiresIn. - If
validFromis provided, it is only used ifvalidUntilis also provided. IfvalidFromis set butvalidUntilis not,validFromwill be ignored.
Validity failures
Credential issuance can fail due to validity misconfiguration in the following scenarios:
- Invalid parameters combinations:
validUntilorvalidFromare in the past.validFromis aftervalidUntil.expiresInis before thevalidFromdate and time (when both are provided).
- Invalid certificates: The validity period of a credential must not exceed the validity period of
the IACA or DSC certificates that form part of its chain of trust. If the
expiresIn,validFrom, orvalidUntilvalues extend beyond the validity of the active IACA or any active DSC at the time of issuance, the credential issuance process will fail. For details on how certificates are selected during mDoc signing, see certificate selection. - mDL-specific failure:
- When the credential type is set to
org.iso.18013.5.*.mDL(where * is a positive integer), and theexpiresInvalue is set to 427 days or more. - When the credential type is set to
org.iso.18013.5.*.mDL(where * is a positive integer), and thevalidUntildate is more than 427 days after the issuance date or thevalidFromdate (if provided).
- When the credential type is set to
Certificate validity and credential type checks are enforced only at the time of credential issuance, not when a credential configuration template is created.
Revocation support
MATTR VII allows you to update the status of issued credentials, enabling you to revoke or suspend credentials when necessary. Verifiers can check the status of a presented credential without compromising the holder’s privacy. Refer to revocation for more information.
Revocation support is configured using the
includeStatus
boolean in the credential configuration. When set to true, issued credentials include a status
object, which refers a Status list where the credential
revocation status is indicated.
Credential branding
Credential configurations can include information regarding how to brand them when they are displayed in a digital wallet. This is useful for enhancing the user experience and ensuring that the credential is easily recognizable.
While display conventions are not yet standardized, MATTR holding and issuance capabilities implement a proprietary format to support branding, clarity, and holder trust. This format includes the following elements:
name: Displayed on the top part of the credential.description: Displayed below the name field.backgroundColor: Applied as the credential background color.watermarkImage: Displayed as a pattern on top of the credential.issuerLogo: Displayed on the bottom part of the credential.issuerIcon: Displayed next to the issuer’s name.
Refer to the API Reference for requirements and best practices for each of these elements.