mDocs Credentials
Create an mDocs Credential 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
/v2/credentials/mobile/configurations
In: header
The mDocs configuration payload
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.
1 <= length <= 1024
This is where you specify how to map claims (user attributes) into issued credentials.
References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.
uuid
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 andvalidFrom
is provided, the expiration date will still be calculated based on the issuance date, not thevalidFrom
value. - Can include any combination of years, months, weeks, days, hours, minutes and seconds.
- If
type
is set toorg.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.
Specifies an explicit date and time from which the credential becomes valid.
- Only available in Pre-authorized Code flows.
- Must be mapped from the provided 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.
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 validFrom
value exceeds the validity of all currently active IACAs at the time of issuance.
Specifies an explicit date and time at which the credential expires.
- Only available in Pre-authorized Code flows.
- Must be mapped from the provided 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 toorg.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 validUntil
value exceeds the validity of all currently active IACAs at the time of issuance.
Used to apply branding to issued credentials.
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.
false
curl -X POST "https://example.vii.au01.mattr.global/v2/credentials/mobile/configurations" \ -H "Content-Type: application/json" \ -d '{}'
{
"id": "983c0a86-204f-4431-9371-f5a22e506599",
"branding": {
"name": "Credential name",
"description": "Credential Description",
"backgroundColor": "#FFFFFF",
"watermarkImage": "data:image/png;base64,{image-data}",
"issuerLogo": "data:image/png;base64,{image-data}",
"issuerIcon": "data:image/svg+xml;base64,{image-data}"
},
"includeStatus": true,
"type": "DriverLicense",
"claimMappings": {
"org.iso.18013.5.1": {
"given_name": {
"mapFrom": "claims.given_name",
"required": true,
"type": "string"
},
"birth_date": {
"mapFrom": "claims.date_of_birth",
"required": true,
"type": "dateTime"
}
}
},
"claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
"expiresIn": {
"years": 0,
"months": 1,
"weeks": 0,
"days": 0,
"hours": 0,
"minutes": 0,
"seconds": 0
},
"validFrom": {
"mapFrom": "string"
},
"validUntil": {
"mapFrom": "string"
}
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Retrieve all mDocs Credential configurations
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
/v2/credentials/mobile/configurations
In: header
Query Parameters
Range size of returned list.
100
1 <= value <= 1000
Starting point for the list of entries.
Optional credential type to filter on
curl -X GET "https://example.vii.au01.mattr.global/v2/credentials/mobile/configurations?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h&type=AlumniCredential"
{
"nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
"data": [
{
"id": "983c0a86-204f-4431-9371-f5a22e506599",
"branding": {
"name": "Credential name",
"description": "Credential Description",
"backgroundColor": "#FFFFFF",
"watermarkImage": "data:image/png;base64,{image-data}",
"issuerLogo": "data:image/png;base64,{image-data}",
"issuerIcon": "data:image/svg+xml;base64,{image-data}"
},
"includeStatus": true,
"type": "DriverLicense",
"claimMappings": {
"org.iso.18013.5.1": {
"given_name": {
"mapFrom": "claims.given_name",
"required": true,
"type": "string"
},
"birth_date": {
"mapFrom": "claims.date_of_birth",
"required": true,
"type": "dateTime"
}
}
},
"claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
"expiresIn": {
"years": 0,
"months": 1,
"weeks": 0,
"days": 0,
"hours": 0,
"minutes": 0,
"seconds": 0
},
"validFrom": {
"mapFrom": "string"
},
"validUntil": {
"mapFrom": "string"
}
}
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Retrieve an mDocs Credential configuration
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
/v2/credentials/mobile/configurations/{id}
In: header
Path Parameters
mDocs configuration ID
uuid
curl -X GET "https://example.vii.au01.mattr.global/v2/credentials/mobile/configurations/3948c40e-6e19-4ffc-933c-91f643f24264"
{
"id": "983c0a86-204f-4431-9371-f5a22e506599",
"branding": {
"name": "Credential name",
"description": "Credential Description",
"backgroundColor": "#FFFFFF",
"watermarkImage": "data:image/png;base64,{image-data}",
"issuerLogo": "data:image/png;base64,{image-data}",
"issuerIcon": "data:image/svg+xml;base64,{image-data}"
},
"includeStatus": true,
"type": "DriverLicense",
"claimMappings": {
"org.iso.18013.5.1": {
"given_name": {
"mapFrom": "claims.given_name",
"required": true,
"type": "string"
},
"birth_date": {
"mapFrom": "claims.date_of_birth",
"required": true,
"type": "dateTime"
}
}
},
"claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
"expiresIn": {
"years": 0,
"months": 1,
"weeks": 0,
"days": 0,
"hours": 0,
"minutes": 0,
"seconds": 0
},
"validFrom": {
"mapFrom": "string"
},
"validUntil": {
"mapFrom": "string"
}
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Update an mDocs Credential configuration
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
/v2/credentials/mobile/configurations/{id}
In: header
Path Parameters
mDocs configuration ID
uuid
Update an mDocs configuration
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.
1 <= length <= 1024
This is where you specify how to map claims (user attributes) into issued credentials.
References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.
uuid
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 andvalidFrom
is provided, the expiration date will still be calculated based on the issuance date, not thevalidFrom
value. - Can include any combination of years, months, weeks, days, hours, minutes and seconds.
- If
type
is set toorg.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.
Specifies an explicit date and time from which the credential becomes valid.
- Only available in Pre-authorized Code flows.
- Must be mapped from the provided 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.
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 validFrom
value exceeds the validity of all currently active IACAs at the time of issuance.
Specifies an explicit date and time at which the credential expires.
- Only available in Pre-authorized Code flows.
- Must be mapped from the provided 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 toorg.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 validUntil
value exceeds the validity of all currently active IACAs at the time of issuance.
Used to apply branding to issued credentials.
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.
false
curl -X PUT "https://example.vii.au01.mattr.global/v2/credentials/mobile/configurations/3948c40e-6e19-4ffc-933c-91f643f24264" \ -H "Content-Type: application/json" \ -d '{}'
{
"id": "983c0a86-204f-4431-9371-f5a22e506599",
"branding": {
"name": "Credential name",
"description": "Credential Description",
"backgroundColor": "#FFFFFF",
"watermarkImage": "data:image/png;base64,{image-data}",
"issuerLogo": "data:image/png;base64,{image-data}",
"issuerIcon": "data:image/svg+xml;base64,{image-data}"
},
"includeStatus": true,
"type": "DriverLicense",
"claimMappings": {
"org.iso.18013.5.1": {
"given_name": {
"mapFrom": "claims.given_name",
"required": true,
"type": "string"
},
"birth_date": {
"mapFrom": "claims.date_of_birth",
"required": true,
"type": "dateTime"
}
}
},
"claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
"expiresIn": {
"years": 0,
"months": 1,
"weeks": 0,
"days": 0,
"hours": 0,
"minutes": 0,
"seconds": 0
},
"validFrom": {
"mapFrom": "string"
},
"validUntil": {
"mapFrom": "string"
}
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
Delete an mDocs Credential configuration
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
/v2/credentials/mobile/configurations/{id}
In: header
Path Parameters
mDocs configuration ID
uuid
curl -X DELETE "https://example.vii.au01.mattr.global/v2/credentials/mobile/configurations/3948c40e-6e19-4ffc-933c-91f643f24264"
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
{
"code": "string",
"message": "string",
"details": [
{
"value": "string",
"msg": "Invalid value",
"param": "id",
"location": "body"
}
]
}
How would you rate this page?