light-mode-image
Learn
Pre-authorized Code flow

API Reference

Create Credential Offer

POST/v1/openid/offers/pre-authorized

Authorization

bearerAuthOpenIdCredentials
AuthorizationBearer <token>

In: header

Request Body

application/json

credentials*array<>

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?object

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

claimsToPersist?array<>

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.vii.au01.mattr.global/v1/openid/offers/pre-authorized" \  -H "Content-Type: application/json" \  -d '{    "credentials": [      "707e920a-f342-443b-ae24-6946b7b5033e"    ]  }'
{
  "id": "string",
  "userId": "string",
  "uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fexample.com%22%2C%22credentials%22%3A%5B%222edaf985-fcc2-4448-9c8e-a04c6c7351c2%22%5D%2C%22credential_configuration_ids%22%3A%5B%222edaf985-fcc2-4448-9c8e-a04c6c7351c2%22%5D%2C%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%22stukD6lg9c9tQ3jUCa32wVi1HI%2BQIVsFK%2FQPvC2CHRs%3D%22%2C%22tx_code%22%3A%7B%22length%22%3A6%2C%22input_mode%22%3A%22numeric%22%2C%22description%22%3A%22Please%20provide%20the%20one-time%20code%20that%20was%20sent%20via%20e-mail%22%7D%7D%7D%7D",
  "expiresAt": "2025-05-01T00:01:00.000Z",
  "transactionCode": 493536
}

Delete Credential Offer

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

Authorization

bearerAuthOpenIdCredentials
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Pre-authorized credential offer ID

Formatuuid

Response Body

application/json

application/json

curl -X DELETE "https://example.vii.au01.mattr.global/v1/openid/offers/pre-authorized/8241400f-de3b-42c5-ad7c-8a380039e796"
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"
    }
  ]
}

Issue a verifiable credential

POST/v1/openid/credential

Authorization

AuthorizationBearer <token>

In: header

Header Parameters

DPoP?string

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

DPoP is offered as a closed beta preview feature and is not generally available yet. If you are interested in trying this feature, please contact us

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

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.vii.au01.mattr.global/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

Response Body

application/json

fetch("https://example.vii.au01.mattr.global/.well-known/openid-credential-issuer", {  method: "GET"})
{
  "issuer": "http://example.com",
  "authorization_endpoint": "http://example.com",
  "jwks_uri": "http://example.com",
  "token_endpoint": "http://example.com",
  "scopes_supported": [
    "ldp_vc:ExampleCredential"
  ],
  "response_types_supported": [
    "code"
  ],
  "response_modes_supported": [
    "query"
  ],
  "grant_types_supported": [
    "authorization_code"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "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": [
        "did:key",
        "mso"
      ],
      "cryptographic_suites_supported": [
        "Ed25519Signature2018",
        "ES256"
      ]
    }
  ],
  "credential_configurations_supported": {
    "2cdb2c15-39a7-4556-abab-4515ce2d831b": {
      "format": "ldp_vc",
      "id": "2cdb2c15-39a7-4556-abab-4515ce2d831b",
      "scope": "ldp_vc:TestCredential",
      "credential_definition": {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          "https://schema.org"
        ],
        "type": [
          "VerifiableCredential",
          "TestCredential"
        ]
      },
      "credential_signing_alg_values_supported": [
        "Ed25519Signature2018",
        "BbsSignatureProof2022"
      ],
      "cryptographic_binding_methods_supported": [
        "did:key"
      ],
      "proof_types_supported": {
        "jwt": {
          "proof_signing_alg_values_supported": [
            "EdDSA"
          ]
        }
      },
      "credential_metadata": {
        "display": [
          {
            "name": "Test Credential",
            "logo": {
              "uri": "https://example.com/logo.png",
              "alt_text": "Example Logo"
            },
            "locale": "en-US",
            "background_color": "#FFFFFF",
            "text_color": "#000000"
          }
        ],
        "claims": [
          {
            "path": [
              "credentialSubject",
              "firstName"
            ],
            "mandatory": true,
            "display": [
              {
                "name": "First Name",
                "locale": "en-US"
              }
            ]
          }
        ]
      }
    },
    "3dfe1c4a-5b6c-4e2f-9f3a-2b1c4d5e6f7g": {
      "format": "cwt_vc",
      "id": "3dfe1c4a-5b6c-4e2f-9f3a-2b1c4d5e6f7g",
      "scope": "cwt_vc:TestCredential",
      "types": [
        "VerifiableCredential",
        "TestCredential"
      ],
      "cryptographic_binding_methods_supported": [],
      "credential_signing_alg_values_supported": [
        -7
      ],
      "credential_metadata": {
        "claims": [
          {
            "path": [
              "vc",
              "credentialSubject",
              "firstName"
            ],
            "mandatory": true,
            "display": [
              {
                "name": "First Name",
                "locale": "en-US"
              }
            ]
          }
        ]
      }
    },
    "b068c060-cc72-4758-9526-92d29edb821f": {
      "format": "cwt",
      "id": "b068c060-cc72-4758-9526-92d29edb821f",
      "scope": "cwt:TestCredential",
      "type": "TestCredential",
      "cryptographic_binding_methods_supported": [],
      "credential_signing_alg_values_supported": [
        -7
      ],
      "credential_metadata": {
        "claims": [
          {
            "path": [
              "firstName"
            ],
            "mandatory": true,
            "display": [
              {
                "name": "First Name",
                "locale": "en-US"
              }
            ]
          }
        ]
      }
    },
    "a1b2c3d4-e5f6-4789-abcd-ef0123456789": {
      "format": "mso_mdoc",
      "doctype": "org.iso.18013.5.1.mDL.T",
      "scope": "mso_mdoc:TestCredential",
      "id": "a1b2c3d4-e5f6-4789-abcd-ef0123456789",
      "cryptographic_binding_methods_supported": [
        "mso"
      ],
      "credential_signing_alg_values_supported": [
        -7
      ],
      "proof_types_supported": {
        "jwt": {
          "proof_signing_alg_values_supported": [
            "ES256"
          ]
        }
      },
      "credential_metadata": {
        "claims": [
          {
            "path": [
              "org.iso.18013.5.1",
              "firstName"
            ],
            "mandatory": true,
            "display": [
              {
                "name": "First Name",
                "locale": "en-US"
              }
            ]
          }
        ],
        "display": [
          {
            "name": "Test Mobile Credential",
            "logo": {
              "uri": "https://example.com/logo.png",
              "alt_text": "Example Logo"
            },
            "locale": "en-US",
            "background_color": "#FFFFFF",
            "text_color": "#000000"
          }
        ]
      }
    }
  },
  "mdoc_iacas_uri": "http://example.com",
  "credential_response_encryption": {
    "alg_values_supported": [
      "HPKE-7"
    ],
    "enc_values_supported": [
      "A256GCM"
    ],
    "encryption_required": false
  },
  "credential_request_encryption": {
    "jwks": {
      "keys": [
        {
          "kty": "EC",
          "kid": "kid",
          "use": "enc",
          "crv": "P-256",
          "alg": "HPKE-7",
          "x": "YO4epjifD-KWeq1sL2tNmm36BhXnkJ0He-WqMYrp9Fk",
          "y": "Hekpm0zfK7C-YccH5iBjcIXgf6YdUvNUac_0At55Okk"
        }
      ]
    },
    "enc_values_supported": [
      "A256GCM"
    ],
    "encryption_required": false
  }
}

How would you rate this page?

Last updated on

Tutorial

Previous Page

Overview

Next Page

On this page

Create Credential Offer
Delete Credential Offer
Issue a verifiable credential
Retrieve issuer metadata