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.

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.
• Availability: Credential configurations must be publicly available to be used in a credential offer. This is to ensure that wallet applications can always access the configuration when they receive a credential offer.

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 : Mobile Driving License (mDL) compliant with the ISO/IEC 18013-5:2021 standard.
• org.iso.23220.photoid.1 : Mobile Photo ID compliant with the ISO/IEC 23220-3:2024 standard.
• eu.europa.ec.eudi.pid.1 : Mobile Person Identification Data compliant with the EU Digital Identity framework.
• org.iso.7367.1.mVRC : Mobile Vehicle Registration Card compliant with the ISO/IEC 7367 standard.
• org.micov.1 : Mobile International Certificate of Vaccination compliant with the WHO guidelines.

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:

{
  "claimMappings": {
    "org.example.studentid.1": {
      "first_name": {
        "defaultValue": "Alice",
        "type": "string"
      },
      "last_name": {
        "defaultValue": "Miller",
        "type": "string"
      },
      "birth_date": {
        "defaultValue": "2001-05-14",
        "type": "date"
      },
      "university_name": {
        "defaultValue": "Kakapo University of Technology",
        "type": "string"
      },
      "student_id": {
        "defaultValue": "12345678",
        "type": "string"
      },
      "program": {
        "defaultValue": "Computer Science",
        "type": "string"
      },
      "enrollment_year": {
        "defaultValue": 2020,
        "type": "number"
      }
    }
  }
}

{
  "claimMappings": {
    "org.example.common.1": {
      "first_name": {
        "defaultValue": "Alice",
        "type": "string"
      },
      "last_name": {
        "defaultValue": "Miller",
        "type": "string"
      },
      "birth_date": {
        "defaultValue": "2001-05-14",
        "type": "date"
      }
    },
    "org.example.university.1": {
      "university_name": {
        "defaultValue": "Kakapo University of Technology",
        "type": "string"
      },
      "student_id": {
        "defaultValue": "12345678",
        "type": "string"
      }
    },
    "org.example.academic.1": {
      "program": {
        "defaultValue": "Computer Science",
        "type": "string"
      },
      "enrollment_year": {
        "defaultValue": 2020,
        "type": "number"
      }
    }
  }
}

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
}

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 contains
  • url : 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, the dateOfBirth claim in the issued credential is mapped directly from claims.dateOfBirth in the user object, and the email claim is mapped from claims.email.
• type : This defines the data type of the claim. Refer to the API Reference for available types and their usage. In this example, both dateOfBirth and email are defined as strings.
• required : When set to true, the claim must be provided during issuance. If it is not provided and no defaultValue is set, issuance will fail. If set to false or not present, the claim is optional and issuance will succeed even if the claim is not provided. In this example, dateOfBirth is a required claim, while email is 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 available is set as the default value for the email claim.

The following logic is applied when combining these properties:

• Either mapFrom or defaultValue must be provided for each claim.
• If mapFrom is provided and the claim is found in the user object, its value will be used.
• If mapFrom is provided but the claim is not found in the user object:
  • If required is true and no defaultValue is provided, issuance will fail.
  • If required is false or not present and a defaultValue is provided, the defaultValue will be used.
  • If required is false or not present and no defaultValue is provided, the claim will be omitted from the issued credential.
• If only defaultValue is provided (without mapFrom), the claim will always be set to the defaultValue.

Best Practices

• Some credential types require a portrait claim. You must provide the portrait as a binary claim type.
• Maximum supported portrait file size is 500KB. Keep files below 50KB for better performance and user experience.

Complex credential structures

Credential configurations support complex data structures, including nested objects and arrays. This enables flexible modeling of real-world data within credential schemas.

The following considerations apply when defining complex structures in the claimMappings object:

• Only standard JSON data types are supported.
• When array or object claims are used, selective disclosure works at the array/object level only. Individual elements cannot be disclosed or hidden independently. This means the holder can either share the entire array/object or omit it. For example, if multiple bank accounts are listed in an array, presenting that claim reveals all accounts, which may have privacy implications.

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.

Here are two examples of how these properties can be used:

{
  "expiresIn": {
    "days": 30
  }

  // Rest of the credential configuration
}

{
  "validFrom": {
    "mapFrom": "claims.validFrom"
  },
  "validUntil": {
    "mapFrom": "claims.validUntil"
  }

  // Rest of the credential configuration
}

The following logic is applied when combining these properties:

Summary of validity decision logic:

1. If validFrom is included in the credential configuration:
   • If validFrom is also provided in user claims, use the value from user claims.
   • Otherwise, use the value from the credential configuration.
2. If validFrom is not included, set the credential's valid from date to the date of issuance.
3. If validUntil is included in the credential configuration:
   • If validUntil is also provided in user claims, use the value from user claims.
   • Otherwise, use the value from the credential configuration.
4. If validUntil is not included, set the credential's valid until date to the date of issuance plus expiresIn.
5. Additional validation:
   • If validUntil is malformed, issuance fails.
   • If validUntil is earlier than validFrom, issuance fails.
   • Otherwise, issuance succeeds.

Validity failures

Credential issuance can fail due to validity misconfiguration in the following scenarios:

• Invalid parameters combinations:
  • validUntil or validFrom are in the past.
  • validFrom is after validUntil.
  • expiresIn is before the validFrom date 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, or validUntil values 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 the expiresIn value 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 the validUntil date is more than 427 days after the issuance date or the validFrom date (if provided).

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 specific requirements for each of these elements.

Availability

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 wallet applications. 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.