Learn

mDoc credentials configuration

Specifies paths and operations for managing mDocs credentials configuration.

Create an mDocs configuration

Creates a new mDocs configuration, a specific set of rules and parameters that are used to create and validate a particular type of verifiable credential. These rules and parameters define how the credential is structured and what data it contains when issued.

Analytic events

  • MOBILE_CREDENTIAL_CONFIGURATION_CREATE_START
  • MOBILE_CREDENTIAL_CONFIGURATION_CREATE_SUCCESS
  • MOBILE_CREDENTIAL_CONFIGURATION_CREATE_FAIL
Roles: ["admin","issuer"]
SecuritybearerAuth
Request
Request Body schema: application/json
required

The mDocs configuration payload

type
required
string [ 1 .. 1024 ] characters

Used to differentiate between different mDocs configurations on your tenant. Thus, its value must:

  • Be unique across all mDocs configurations on your tenant.
  • Not be VerifiableCredential.
  • When set to org.iso.18013.5.*.mDL (where * is a positive integer), MATTR VII recognizes that this is attempt to create an mDL credential configuration and will fail if the validity period is set to 427 days or more.
required
object (ClaimMappings)

This is where you specify how to map claims (user attributes) into issued credentials.

claimSourceId
string <uuid>

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

required
object

Used to determine when issued credentials will expire, relative to issuance date:

  • Ignored if a valid validUntil date/time is provided.
  • Cannot be before the validFrom date/time.
  • If expiresIn is used to determine the credential's expiry date and validFrom is provided, the expiration date will still be calculated based on the issuance date, not the validFrom value.
  • Can include any combination of years, months, weeks, days, hours, minutes and seconds.
  • If type is set to org.iso.18013.5.*.mDL (for issuing an mDL), the maximum validity is 427 days.
  • For any other type, the maximum validity is 3620 days.

Credential expiry can never exceed the validity period of the IACA used as the root certificate when signing the credential. However, all validity checks (including those for IACA and credential validity periods) only occur when an individual credential is being signed, not when the generic credential configuration template is created (Refer to IACA selection for more information on how an IACA is selected when signing an mDoc). As a result, issuance will fail if the expiresIn value exceeds the validity of all currently active IACAs at the time of issuance.

object

Specifies an explicit date and time from which the credential becomes valid.

  • Derived from the user claims.
  • Must be formatted as a valid ISO 8601 date/time string.
  • If not provided, defaults to using the issuance date as the starting point for the credential's validity.
  • Cannot be after the credential's expiration date/time.
  • Cannot be before the credential's issuance date/time.
object

Specifies an explicit date and time at which the credential expires.

  • Derived from the user claims.
  • Must be formatted as a valid ISO 8601 date/time string.
  • If not provided, the expiration date will be determined based on the expiresIn value provided in the credential configuration.
  • Cannot be before the validFrom date/time.
  • If type is set to org.iso.18013.5.*.mDL (for issuing an mDL), the maximum validity is 427 days.
  • For any other type, the maximum validity is 3620 days.

Credential expiry can never exceed the validity period of the IACA used as the root certificate when signing the credential. However, all validity checks (including those for IACA and credential validity periods) only occur when an individual credential is being signed, not when the generic credential configuration template is created (Refer to IACA selection for more information on how an IACA is selected when signing an mDoc). As a result, issuance will fail if the expiresIn value exceeds the validity of all currently active IACAs at the time of issuance.

object

Used to apply branding to issued credentials.

includeStatus
boolean
Default: false

When set to true, issued mDocs are revocable. They include a status object, which refers a Status list where the mDoc status is indicated. Revocable mDocs are issued as valid by default, but this status can later be changed to invalid, or suspended.

Responses
201

mDocs configuration created

400

Bad Request. The request was malformed or missing required parameters.

post/v2/credentials/mobile/configurations
Request samples
application/json
{
  • "type": "DriverLicense",
  • "claimMappings": {
    },
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    },
  • "validFrom": {
    },
  • "validUntil": {
    },
  • "branding": {
    },
  • "includeStatus": true
}
Response samples
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "branding": {
    },
  • "includeStatus": true,
  • "type": "DriverLicense",
  • "claimMappings": {
    },
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    },
  • "validFrom": {
    },
  • "validUntil": {
    }
}

Retrieve all mDocs configurations

Retrieves all mDocs configurations from your tenant.

Analytic events

  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_START
  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_SUCCESS
  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_FAIL
Roles: ["admin","issuer"]
SecuritybearerAuth
Request
query Parameters
limit
number [ 1 .. 1000 ]
Default: 100

Range size of returned list.

Example: limit=2
cursor
string

Starting point for the list of entries.

Example: cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h
type
string

Optional credential type to filter on

Example: type=AlumniCredential
Responses
200

mDocs configurations retrieved

400

Bad Request. The request was malformed or missing required parameters.

get/v2/credentials/mobile/configurations
Request samples 
Response samples 
application/json
{
  • "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  • "data": [
    ]
}
Retrieve an mDocs configuration
Retrieves an existing mDocs configuration by providing its ID.


Analytic events


    

  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_START
    • 

  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_SUCCESS
    • 

  • MOBILE_CREDENTIAL_CONFIGURATION_RETRIEVE_FAIL
    • 



Roles:  ["admin","issuer"]
SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
mDocs configuration ID


 
 Example:  3948c40e-6e19-4ffc-933c-91f643f24264
Responses 
200
mDocs configuration retrieved


400
Bad Request. The request was malformed or missing required parameters.


404
Not Found. The specified resource was not found.


get/v2/credentials/mobile/configurations/{id}
Request samples 
Response samples 
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "branding": {
    },
  • "includeStatus": true,
  • "type": "DriverLicense",
  • "claimMappings": {
    },
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    },
  • "validFrom": {
    },
  • "validUntil": {
    }
}
Update an mDocs configuration
Updates an existing mDocs configuration by providing its ID.


Analytic events


    

  • MOBILE_CREDENTIAL_CONFIGURATION_UPDATE_START
    • 

  • MOBILE_CREDENTIAL_CONFIGURATION_UPDATE_SUCCESS
    • 

  • MOBILE_CREDENTIAL_CONFIGURATION_UPDATE_FAIL
    • 



Roles:  ["admin","issuer"]
SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
mDocs configuration ID


 
 Example:  3948c40e-6e19-4ffc-933c-91f643f24264
Request Body schema: application/json
required
Update an mDocs configuration


type
required
string  [ 1 .. 1024 ] characters 
Used to differentiate between different mDocs configurations on your tenant. Thus, its value must:


    

  • Be unique across all mDocs configurations on your tenant.
    • 

  • Not be VerifiableCredential.
    • 

  • When set to org.iso.18013.5.*.mDL (where * is a positive integer), MATTR VII recognizes that this is attempt to create an mDL credential configuration and will fail if the validity period is set to 427 days or more.
    • 



 
required
object (ClaimMappings) 
This is where you specify how to map claims (user attributes) into issued credentials.


 
claimSourceId
string <uuid> 
References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.


 
required
object
Used to determine when issued credentials will expire, relative to issuance date:


    

  • Ignored if a valid validUntil date/time is provided.
    • 

  • Cannot be before the validFrom date/time.
    • 

  • If expiresIn is used to determine the credential's expiry date and validFrom is provided, the expiration date will still be calculated based on the issuance date, not the validFrom value.
    • 

  • Can include any combination of years, months, weeks, days, hours, minutes and seconds. 
    • 

  • If type is set to org.iso.18013.5.*.mDL (for issuing an mDL), the maximum validity is 427 days.
    • 

  • For any other type, the maximum validity is 3620 days.
    • 



Credential expiry can never exceed the validity period of the IACA used as the root certificate when signing the credential. However, all validity checks (including those for IACA and credential validity periods) only occur when an individual credential is being signed, not when the generic credential configuration template is created (Refer to IACA selection for more information on how an IACA is selected when signing an mDoc). As a result, issuance will fail if the expiresIn value exceeds the validity of all currently active IACAs at the time of issuance.


 
object
Specifies an explicit date and time from which the credential becomes valid. 


    

  • Derived from the user claims.
    • 

  • Must be formatted as a valid ISO 8601 date/time string. 
    • 

  • If not provided, defaults to using the issuance date as the starting point for the credential's validity.
    • 

  • Cannot be after the credential's expiration date/time.
    • 

  • Cannot be before the credential's issuance date/time.
    • 



 
object
Specifies an explicit date and time at which the credential expires. 


    

  • Derived from the user claims.
    • 

  • Must be formatted as a valid ISO 8601 date/time string. 
    • 

  • If not provided, the expiration date will be determined based on the expiresIn value provided in the credential configuration.
    • 

  • Cannot be before the validFrom date/time.
    • 

  • If type is set to org.iso.18013.5.*.mDL (for issuing an mDL), the maximum validity is 427 days.
    • 

  • For any other type, the maximum validity is 3620 days.
    • 



Credential expiry can never exceed the validity period of the IACA used as the root certificate when signing the credential. However, all validity checks (including those for IACA and credential validity periods) only occur when an individual credential is being signed, not when the generic credential configuration template is created (Refer to IACA selection for more information on how an IACA is selected when signing an mDoc). As a result, issuance will fail if the expiresIn value exceeds the validity of all currently active IACAs at the time of issuance.


 
object
Used to apply branding to issued credentials.


 
includeStatus
boolean
 Default:  false
When set to true, issued mDocs are revocable. They include a status object, which refers a Status list where the mDoc status is indicated. Revocable mDocs are issued as valid by default, but this status can later be changed to invalid, or suspended.


 
Responses 
200
mDocs configuration updated


400
Bad Request. The request was malformed or missing required parameters.


404
Not Found. The specified resource was not found.


put/v2/credentials/mobile/configurations/{id}
Request samples 
application/json
{
  • "type": "DriverLicense",
  • "claimMappings": {
    },
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    },
  • "validFrom": {
    },
  • "validUntil": {
    },
  • "branding": {
    },
  • "includeStatus": true
}
Response samples 
application/json
{
  • "id": "983c0a86-204f-4431-9371-f5a22e506599",
  • "branding": {
    },
  • "includeStatus": true,
  • "type": "DriverLicense",
  • "claimMappings": {
    },
  • "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  • "expiresIn": {
    },
  • "validFrom": {
    },
  • "validUntil": {
    }
}
Delete an mDocs configuration
Deletes an existing mDocs configuration by providing its ID.


Analytic events


    

  • MOBILE_CREDENTIAL_CONFIGURATION_DELETE_START
    • 

  • MOBILE_CREDENTIAL_CONFIGURATION_DELETE_SUCCESS
    • 

  • MOBILE_CREDENTIAL_CONFIGURATION_DELETE_FAIL
    • 



Roles:  ["admin","issuer"]
SecuritybearerAuth 
Request 
path Parameters
id
required
string <uuid> 
mDocs configuration ID


 
 Example:  3948c40e-6e19-4ffc-933c-91f643f24264
Responses 
204
mDocs configuration deleted


400
Bad Request. The request was malformed or missing required parameters.


404
Not Found. The specified resource was not found.


delete/v2/credentials/mobile/configurations/{id}
Request samples 
Response samples 
application/json
{
  • "code": "string",
  • "type": "string",
  • "message": "string",
  • "details": [
    ]
}
➔ Next to Credential issuance