MATTR Learn

Create an mDocs Credential configuration

POST/v2/credentials/mobile/configurations

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

The mDocs configuration payload

type*string

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.

Length1 <= length <= 1024

claimMappings*

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

claimSourceId?string

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

Formatuuid

expiresIn*

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.

validFrom?

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

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.

validUntil?

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

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 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 validUntil value exceeds the validity of all currently active IACAs at the time of issuance.

branding?

Used to apply branding to issued credentials.

includeStatus?boolean

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.

Defaultfalse

Response Body

`application/json`

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": "org.iso.18013.5.1.mDL",
  "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

GET/v2/credentials/mobile/configurations

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

limit?number

Range size of returned list.

Default100

Range1 <= value <= 1000

cursor?string

Starting point for the list of entries.

type?string

Optional credential type to filter on

Response Body

`application/json`

curl -X GET "https://example.vii.au01.mattr.global/v2/credentials/mobile/configurations"

{
  "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": "org.iso.18013.5.1.mDL",
      "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

GET/v2/credentials/mobile/configurations/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

mDocs configuration ID

Formatuuid

Response Body

`application/json`

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": "org.iso.18013.5.1.mDL",
  "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

PUT/v2/credentials/mobile/configurations/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

mDocs configuration ID

Formatuuid

Request Body

application/json

Update an mDocs configuration

type*string

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.

Length1 <= length <= 1024

claimMappings*

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

claimSourceId?string

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

Formatuuid

expiresIn*

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.

validFrom?

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

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.

validUntil?

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

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 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 validUntil value exceeds the validity of all currently active IACAs at the time of issuance.

branding?

Used to apply branding to issued credentials.

includeStatus?boolean

Defaultfalse

Response Body

`application/json`

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": "org.iso.18013.5.1.mDL",
  "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/v2/credentials/mobile/configurations/{id}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

mDocs configuration ID

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.vii.au01.mattr.global/v2/credentials/mobile/configurations/3948c40e-6e19-4ffc-933c-91f643f24264"

Empty

{
  "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"
    }
  ]
}

mDocs Credentials

Create an mDocs Credential configuration

Authorization

Request Body

Response Body

`application/json`

`application/json`

Retrieve all mDocs Credential configurations

Authorization

Query Parameters

Response Body

`application/json`

`application/json`

Retrieve an mDocs Credential configuration

Authorization

Path Parameters

Response Body

`application/json`

`application/json`

`application/json`

Update an mDocs Credential configuration

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/json`

`application/json`

Delete an mDocs Credential configuration

Authorization

Path Parameters

Response Body

`application/json`

`application/json`

On this page

mDocs Credentials

201application/json

400application/json

200application/json

400application/json

200application/json

400application/json

404application/json

200application/json

400application/json

404application/json

204

400application/json

404application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`