light-mode-image
Learn
Pre-authorized Code flow

API Reference

Create Credential Offer

Create a Pre-Authorized Code credential offer

Generate a new OpenID4VCI Pre-Authorized Code credential offer.

ℹ️ Note: The Pre-authorized Code flow is only supported for the mDocs credential format.

Analytic events

  • OPENID_PRE_AUTHORIZED_OFFER_CREATE_START
  • OPENID_PRE_AUTHORIZED_OFFER_CREATE_SUCCESS
  • OPENID_PRE_AUTHORIZED_OFFER_CREATE_FAIL
POST/v1/openid/offers/pre-authorized

Authorization

AuthorizationBearer <token>

In: header

Request Body

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

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.

claims?object

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

Empty Object

claimsToPersist?array<string>

List of claims to persist from the provided claims to MATTR VII. By default no claim values are persisted.

expiresIn?object

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.

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%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 a Pre-authorized Code credential offer

Delete an OpenID4VCI Pre-authorized Code credential offer.

Analytic events

  • OPENID_PRE_AUTHORIZED_OFFER_DELETE_START
  • OPENID_PRE_AUTHORIZED_OFFER_DELETE_SUCCESS
  • OPENID_PRE_AUTHORIZED_OFFER_DELETE_FAIL
DELETE/v1/openid/offers/pre-authorized/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

Pre-authorized credential offer ID

Formatuuid
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

Issue a verifiable credential

Issues a credential to a holder upon presentation of a valid access token, as per OpenID4VCI.

The valid access token must be provided in the following header format: Authorization: Bearer <access_token>.

Analytic events

  • OPENID_CREDENTIAL_START
  • OPENID_CREDENTIAL_SUCCESS
  • OPENID_CREDENTIAL_FAIL
POST/v1/openid/credential

Authorization

AuthorizationBearer <token>

In: header

Request Body

formatstring

Credential format, always ldp_vc for JSON credentials.

Value in"ldp_vc"
credential_definitionobject
proof?object

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

formatstring

Credential format, always cwt for CWT credentials.

Value in"cwt"
typestring
formatstring

Credential format, always cwt_vc for Semantic CWT credentials.

Value in"cwt_vc"
typesarray<string>
formatstring

Credential format, always mso_mdoc for mDocs.

Value in"mso_mdoc"
doctypestring

The document type identifier for the credential, as defined in ISO/IEC 18013-5:2021.

proof?object

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

curl -X POST "https://example.vii.au01.mattr.global/v1/openid/credential" \  -H "Content-Type: application/json" \  -d '{    "format": "ldp_vc",    "credential_definition": {      "type": [        "VerifiableCredential",        "AlumniCredential"      ],      "@context": [        "https://www.w3.org/2018/credentials/v1"      ]    },    "proof": {      "proof_type": "jwt",      "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."    }  }'
{
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "type": [
      "VerifiableCredential",
      "AlumniCredential"
    ],
    "issuer": {
      "id": "did:web:organization.com",
      "name": "Example University",
      "logoUrl": "https://example.edu/img/logo.png",
      "iconUrl": "https://example.edu/img/icon.png"
    },
    "credentialBranding": {
      "backgroundColor": "#B00AA0",
      "watermarkImageUrl": "https://example.edu/img/watermark.png"
    },
    "issuanceDate": "2020-05-02T12:06:29.156Z",
    "credentialStatus": {
      "id": "https://tenant.vii.mattr.global/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3#1",
      "type": "RevocationList2020Status",
      "revocationListIndex": 1,
      "revocationListCredential": "https://tenant.vii.mattr.global/v1/revocation-lists/cc641396-3750-43c8-b8b8-f30d74eb3fb3"
    },
    "credentialSubject": {
      "givenName": "Jamie",
      "familyName": "Doe",
      "alumniOf": "Example University"
    },
    "proof": {
      "type": "Ed25519Signature2018",
      "created": "2020-05-02T12:06:29Z",
      "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "did:web:organization.com"
    },
    "name": "Alumni Credential",
    "description": "This credential shows that the person has attended the mentioned university."
  },
  "format": "ldp_vc"
}

Retrieve issuer metadata

Retrieve OpenID4VCI issuer metadata

Returns OpenID4VCI issuer metadata. This is the standard OpenID4VCI 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 OpenID4VCI capabilities.

GET/.well-known/openid-credential-issuer
curl -X GET "https://example.vii.au01.mattr.global/.well-known/openid-credential-issuer"
{
  "issuer": "http://example.com",
  "authorization_endpoint": "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": "string",
      "cryptographic_suites_supported": "string"
    }
  ],
  "mdoc_iacas_uri": "http://example.com"
}

How would you rate this page?

Tutorial

Previous Page

Overview

Next Page

On this page

Create Credential OfferDelete Credential OfferIssue a verifiable credentialRetrieve issuer metadata