API Reference

Create Credential Offer

POST/v1/openid/offers/pre-authorized

Generate a new OID4VCI Pre-Authorized Code credential offer.

This offer can only be used once. Once the offer is successfully claimed and the credential is issued, the pre-authorized code is consumed and the offer becomes invalid. The offer cannot be claimed again, even if the same user attempts to claim it. This is a security measure to prevent unauthorized credential duplication. If you need to issue another credential to the same user, you must generate a new credential offer.

The total size of the request cannot exceed 500KB, including any claims. This is mostly relevant when including large claims such as images. When holders present credentials over Bluetooth Low Energy (BLE), keep payloads as small as practical, as large claims can degrade the transfer experience. Reserve larger payloads for remote presentation flows.

Roles

adminissuermanaged-issuer

Analytics Events

OPENID_PRE_AUTHORIZED_OFFER_CREATE_STARTOPENID_PRE_AUTHORIZED_OFFER_CREATE_SUCCESSOPENID_PRE_AUTHORIZED_OFFER_CREATE_FAIL

Authorization

bearerAuthOpenIdCredentials

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://example.com/v1/openid/offers/pre-authorized" \  -H "Content-Type: application/json" \  -d '{    "credentials": [      "string"    ]  }'

{  "id": "string",  "userId": "string",  "uri": "string",  "expiresAt": 0,  "transactionCode": "string"}

Delete Credential Offer

DELETE/v1/openid/offers/pre-authorized/{id}

Delete an OID4VCI Pre-authorized Code credential offer.

Roles

adminissuermanaged-issuer

Analytics Events

OPENID_PRE_AUTHORIZED_OFFER_DELETE_STARTOPENID_PRE_AUTHORIZED_OFFER_DELETE_SUCCESSOPENID_PRE_AUTHORIZED_OFFER_DELETE_FAIL

Authorization

bearerAuthOpenIdCredentials

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Pre-authorized credential offer ID

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/openid/offers/pre-authorized/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

Issue a verifiable credential

POST/v1/openid/credential

Issues a credential to a holder upon presentation of a valid access token, as per OID4VCI. Supports encrypted and non-encrypted credential issuance.

For non-encrypted credential issuance the valid access token must be provided in one of the following header formats:

Bearer

Authorization: Bearer <access_token>.
Content-Type: application/json
Body: <credential request payload>

DPoP Only required when using DPoP-bound access tokens.

Authorization: DPoP <access_token>.
DPoP: <dpop_token>
Content-Type: application/json
Body: <credential request payload>

For encrypted credential issuance, contact us to configure how your MATTR VII enforces request and/or response encryption, and then:

For request encryption, Content-Type must be set to application/jwt and the payload must be JWE formatted.
For response encryption, include the credential_response_encryption property in the raw request payload to specify encryption details.

Analytics Events

OPENID_CREDENTIAL_STARTOPENID_CREDENTIAL_SUCCESSOPENID_CREDENTIAL_FAIL

Authorization

AuthorizationBearer <token>

In: header

Header Parameters

DPoP?string

DPoP proof JWT. A signed JWT that demonstrates proof-of-possession of a private key.

When to use:

Token endpoint: Required when dpop_jkt was provided in the authorization request
Credential endpoint: Required when using DPoP-bound access tokens (Authorization header must use format: Authorization: DPoP <access_token>)

The DPoP proof must be a signed JWT with the following structure:

Header:

alg: Must be ES256
typ: Must be dpop+jwt
jwk: Public key (JWK format)

Payload:

htu: HTTP URI of the target endpoint
htm: HTTP method (e.g., POST)
jti: Unique identifier for this DPoP proof
iat: Unix timestamp when the DPoP proof was created
ath: Optional base64url-encoded SHA-256 hash of the access_token. Required when authenticating with the resource server.
htcd: Optional base64-encoded SHA-256 hash (content digest) of the HTTP request payload used to validate integrity.

Each DPoP proof must be unique and cannot be reused across requests.

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

Credential request payload for unencrypted credential requests

Response Body

curl -X POST "https://example.com/v1/openid/credential" \  -H "Content-Type: application/json" \  -d '{    "credential_configuration_id": "2cdb2c15-39a7-4556-abab-4515ce2d831b",    "proofs": {      "jwt": [        "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."      ]    }  }'

{  "credentials": [    {      "credential": {        "@context": [          "https://www.w3.org/2018/credentials/v1"        ],        "id": "http://example.edu/credentials/3732",        "type": [          "VerifiableCredential",          "AlumniCredential"        ],        "issuer": "https://example.edu/issuers/14",        "issuanceDate": "2020-03-10T04:24:12.164Z",        "credentialSubject": {          "id": "did:example:123",          "alumniOf": "Example University"        },        "proof": {          "type": "RsaSignature2018",          "created": "2020-03-10T04:24:12Z",          "proofPurpose": "assertionMethod",          "verificationMethod": "https://example.edu/issuers/keys/1",          "jws": "EXAMPLE_JWS_TOKEN_eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9aH0..."        }      }    }  ]}

Retrieve issuer metadata

GET/.well-known/openid-credential-issuer

Returns OID4VCI issuer metadata. This is the standard OID4VCI Well Known endpoint for your tenant.

This endpoint is unprotected, public facing and can be deterministically found at the root of the tenant subdomain or alias by any party wishing to discover the OID4VCI capabilities.

Response Body

`application/json`

curl -X GET "https://example.com/.well-known/openid-credential-issuer"

{  "issuer": "http://example.com",  "authorization_endpoint": "http://example.com",  "jwks_uri": "http://example.com",  "token_endpoint": "http://example.com",  "scopes_supported": [    "string"  ],  "response_types_supported": [    "string"  ],  "response_modes_supported": [    "string"  ],  "grant_types_supported": [    "string"  ],  "code_challenge_methods_supported": [    "string"  ],  "credential_issuer": "http://example.com",  "credential_endpoint": "http://example.com",  "credentials_supported": [    {      "format": "string",      "id": "string",      "scope": "string",      "@context": [        "string"      ],      "type": [        "string"      ],      "credentialSubject": {},      "cryptographic_binding_methods_supported": [        "string"      ],      "cryptographic_suites_supported": [        "string"      ]    }  ],  "credential_configurations_supported": {    "property1": {      "format": "string",      "id": "string",      "scope": "string",      "credential_definition": {        "type": [          "string"        ],        "@context": [          "string"        ]      },      "credential_signing_alg_values_supported": [        "string"      ],      "cryptographic_binding_methods_supported": [        "string"      ],      "proof_types_supported": {        "jwt": {          "proof_signing_alg_values_supported": [            "string"          ],          "key_attestations_required": {            "key_storage": [              "string"            ],            "user_authentication": [              "string"            ]          }        }      },      "credential_metadata": {        "display": [          {}        ],        "claims": [          {            "path": [              "string"            ],            "mandatory": true,            "display": [              {                "name": "string",                "locale": "string"              }            ]          }        ]      }    },    "property2": {      "format": "string",      "id": "string",      "scope": "string",      "credential_definition": {        "type": [          "string"        ],        "@context": [          "string"        ]      },      "credential_signing_alg_values_supported": [        "string"      ],      "cryptographic_binding_methods_supported": [        "string"      ],      "proof_types_supported": {        "jwt": {          "proof_signing_alg_values_supported": [            "string"          ],          "key_attestations_required": {            "key_storage": [              "string"            ],            "user_authentication": [              "string"            ]          }        }      },      "credential_metadata": {        "display": [          {}        ],        "claims": [          {            "path": [              "string"            ],            "mandatory": true,            "display": [              {                "name": "string",                "locale": "string"              }            ]          }        ]      }    }  },  "mdoc_iacas_uri": "http://example.com",  "credential_response_encryption": {    "alg_values_supported": [      "string"    ],    "enc_values_supported": [      "string"    ],    "encryption_required": true  },  "credential_request_encryption": {    "jwks": {      "keys": [        {          "kty": "string",          "kid": "string",          "use": "string",          "crv": "string",          "alg": "string",          "x": "string",          "y": "string"        }      ]    },    "enc_values_supported": [      "string"    ],    "encryption_required": true  }}

Create Credential Offer

POST/v1/openid/offers/pre-authorized

Generate a new OID4VCI Pre-Authorized Code credential offer.

Roles

adminissuermanaged-issuer

Analytics Events

OPENID_PRE_AUTHORIZED_OFFER_CREATE_STARTOPENID_PRE_AUTHORIZED_OFFER_CREATE_SUCCESSOPENID_PRE_AUTHORIZED_OFFER_CREATE_FAIL

Authorization

bearerAuthOpenIdCredentials

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

credentials*array<string>

This array includes a list of identifiers for mDocs credential configurations that will be included in the credential offer. These identifiers are the id elements returned in the response when you create a credential configuration. Providing the identifier of a non-mDocs credential configuration will result in an error.

userId?string

Unique system generated identifier to reference the user for this offer. This can be obtained by searching for a user. If not provided, a new user entity will be created.

transactionCodeConfiguration?

Configure whether a second-factor transaction code is required for this offer. If a configuration is provided, a code will be generated for the offer, and the end user must submit it during credential retrieval. If an incorrect transaction code is entered three times by the holder, the credential offer is permanently invalidated and the wallet can no longer claim the credential.

claims?

Additional user claims that are available during credential issuance for this offer.

claimsToPersist?array<string>

This array includes a list of claims that will be persisted against the user object in the MATTR VII database. These claims are then available for any future credential offers or issuance operations for this user. By default no claims are persisted, and it is recommended to consider carefully which claims to persist, if any, as this has implications for data privacy and security.

expiresIn?

Specifies when the offer will expire. Once the offer expires, the user can no longer use it to claim a credential, and a new offer must be generated. The expiration period can include any combination of minutes and seconds. By default, the offer expires in 5 minutes, and the maximum allowed duration is 10 minutes.

Response Body

`application/json`

curl -X POST "https://example.com/v1/openid/offers/pre-authorized" \  -H "Content-Type: application/json" \  -d '{    "credentials": [      "string"    ]  }'

{  "id": "string",  "userId": "string",  "uri": "string",  "expiresAt": 0,  "transactionCode": "string"}

Delete Credential Offer

DELETE/v1/openid/offers/pre-authorized/{id}

Delete an OID4VCI Pre-authorized Code credential offer.

Roles

adminissuermanaged-issuer

Analytics Events

OPENID_PRE_AUTHORIZED_OFFER_DELETE_STARTOPENID_PRE_AUTHORIZED_OFFER_DELETE_SUCCESSOPENID_PRE_AUTHORIZED_OFFER_DELETE_FAIL

Authorization

bearerAuthOpenIdCredentials

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Pre-authorized credential offer ID

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/openid/offers/pre-authorized/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

Issue a verifiable credential

POST/v1/openid/credential

Issues a credential to a holder upon presentation of a valid access token, as per OID4VCI. Supports encrypted and non-encrypted credential issuance.

For non-encrypted credential issuance the valid access token must be provided in one of the following header formats:

Bearer

Authorization: Bearer <access_token>.
Content-Type: application/json
Body: <credential request payload>

DPoP Only required when using DPoP-bound access tokens.

Authorization: DPoP <access_token>.
DPoP: <dpop_token>
Content-Type: application/json
Body: <credential request payload>

For encrypted credential issuance, contact us to configure how your MATTR VII enforces request and/or response encryption, and then:

For request encryption, Content-Type must be set to application/jwt and the payload must be JWE formatted.
For response encryption, include the credential_response_encryption property in the raw request payload to specify encryption details.

Analytics Events

OPENID_CREDENTIAL_STARTOPENID_CREDENTIAL_SUCCESSOPENID_CREDENTIAL_FAIL

Authorization

AuthorizationBearer <token>

In: header

Header Parameters

DPoP?string

DPoP proof JWT. A signed JWT that demonstrates proof-of-possession of a private key.

When to use:

Token endpoint: Required when dpop_jkt was provided in the authorization request
Credential endpoint: Required when using DPoP-bound access tokens (Authorization header must use format: Authorization: DPoP <access_token>)

The DPoP proof must be a signed JWT with the following structure:

Header:

alg: Must be ES256
typ: Must be dpop+jwt
jwk: Public key (JWK format)

Payload:

htu: HTTP URI of the target endpoint
htm: HTTP method (e.g., POST)
jti: Unique identifier for this DPoP proof
iat: Unix timestamp when the DPoP proof was created
ath: Optional base64url-encoded SHA-256 hash of the access_token. Required when authenticating with the resource server.
htcd: Optional base64-encoded SHA-256 hash (content digest) of the HTTP request payload used to validate integrity.

Each DPoP proof must be unique and cannot be reused across requests.

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

Credential request payload for unencrypted credential requests

credential_configuration_id*string

Credential configuration identifier.

proofs?

JSON object containing proof of possession of the key material the issued Credential shall be bound to.

credential_response_encryption?

JSON object containing details for encrypting the issued credential in the response.

Response Body

curl -X POST "https://example.com/v1/openid/credential" \  -H "Content-Type: application/json" \  -d '{    "credential_configuration_id": "2cdb2c15-39a7-4556-abab-4515ce2d831b",    "proofs": {      "jwt": [        "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."      ]    }  }'

{  "credentials": [    {      "credential": {        "@context": [          "https://www.w3.org/2018/credentials/v1"        ],        "id": "http://example.edu/credentials/3732",        "type": [          "VerifiableCredential",          "AlumniCredential"        ],        "issuer": "https://example.edu/issuers/14",        "issuanceDate": "2020-03-10T04:24:12.164Z",        "credentialSubject": {          "id": "did:example:123",          "alumniOf": "Example University"        },        "proof": {          "type": "RsaSignature2018",          "created": "2020-03-10T04:24:12Z",          "proofPurpose": "assertionMethod",          "verificationMethod": "https://example.edu/issuers/keys/1",          "jws": "EXAMPLE_JWS_TOKEN_eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9aH0..."        }      }    }  ]}

Retrieve issuer metadata

GET/.well-known/openid-credential-issuer

Returns OID4VCI issuer metadata. This is the standard OID4VCI Well Known endpoint for your tenant.

This endpoint is unprotected, public facing and can be deterministically found at the root of the tenant subdomain or alias by any party wishing to discover the OID4VCI capabilities.

Response Body

`application/json`

curl -X GET "https://example.com/.well-known/openid-credential-issuer"

{  "issuer": "http://example.com",  "authorization_endpoint": "http://example.com",  "jwks_uri": "http://example.com",  "token_endpoint": "http://example.com",  "scopes_supported": [    "string"  ],  "response_types_supported": [    "string"  ],  "response_modes_supported": [    "string"  ],  "grant_types_supported": [    "string"  ],  "code_challenge_methods_supported": [    "string"  ],  "credential_issuer": "http://example.com",  "credential_endpoint": "http://example.com",  "credentials_supported": [    {      "format": "string",      "id": "string",      "scope": "string",      "@context": [        "string"      ],      "type": [        "string"      ],      "credentialSubject": {},      "cryptographic_binding_methods_supported": [        "string"      ],      "cryptographic_suites_supported": [        "string"      ]    }  ],  "credential_configurations_supported": {    "property1": {      "format": "string",      "id": "string",      "scope": "string",      "credential_definition": {        "type": [          "string"        ],        "@context": [          "string"        ]      },      "credential_signing_alg_values_supported": [        "string"      ],      "cryptographic_binding_methods_supported": [        "string"      ],      "proof_types_supported": {        "jwt": {          "proof_signing_alg_values_supported": [            "string"          ],          "key_attestations_required": {            "key_storage": [              "string"            ],            "user_authentication": [              "string"            ]          }        }      },      "credential_metadata": {        "display": [          {}        ],        "claims": [          {            "path": [              "string"            ],            "mandatory": true,            "display": [              {                "name": "string",                "locale": "string"              }            ]          }        ]      }    },    "property2": {      "format": "string",      "id": "string",      "scope": "string",      "credential_definition": {        "type": [          "string"        ],        "@context": [          "string"        ]      },      "credential_signing_alg_values_supported": [        "string"      ],      "cryptographic_binding_methods_supported": [        "string"      ],      "proof_types_supported": {        "jwt": {          "proof_signing_alg_values_supported": [            "string"          ],          "key_attestations_required": {            "key_storage": [              "string"            ],            "user_authentication": [              "string"            ]          }        }      },      "credential_metadata": {        "display": [          {}        ],        "claims": [          {            "path": [              "string"            ],            "mandatory": true,            "display": [              {                "name": "string",                "locale": "string"              }            ]          }        ]      }    }  },  "mdoc_iacas_uri": "http://example.com",  "credential_response_encryption": {    "alg_values_supported": [      "string"    ],    "enc_values_supported": [      "string"    ],    "encryption_required": true  },  "credential_request_encryption": {    "jwks": {      "keys": [        {          "kty": "string",          "kid": "string",          "use": "string",          "crv": "string",          "alg": "string",          "x": "string",          "y": "string"        }      ]    },    "enc_values_supported": [      "string"    ],    "encryption_required": true  }}

Roles

Analytics Events

200application/json

Roles

Analytics Events

204

400application/json

404application/json

Analytics Events

200application/json

Response to issue a JSON credential

Response to issue a Semantic CWT credential

Response to issue a CWT credential

Response to issue an mDocs credential

Response to issue a JSON credential (deprecated)

Response to issue a Semantic CWT credential (deprecated)

Response to issue a CWT credential (deprecated)

Response to issue an mDocs credential (deprecated)

200application/json

On this page

API Reference

Roles

Analytics Events

200application/json

Roles

Analytics Events

204

400application/json

404application/json

Analytics Events

200application/json

Response to issue a JSON credential

Response to issue a Semantic CWT credential

Response to issue a CWT credential

Response to issue an mDocs credential

Response to issue a JSON credential (deprecated)

Response to issue a Semantic CWT credential (deprecated)

Response to issue a CWT credential (deprecated)

Response to issue an mDocs credential (deprecated)

200application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`