Verifiable Credential Issuance

Get credential receive states

get

Get credential receive states.

Authorizations

bearerAuthmutualTLS

AuthorizationstringOptional

Bearer authentication header of the form Bearer <token>.

Path parameters

walletIdstringRequired

Query parameters

orderstring · enumOptional

Issuance state response order. Default ordering: DESC (Supported: ASC, DESC)

Example: DESCPossible values:

order_bystring · enumOptional

Order Issuance state by an attribute, defaults to: created_at (Supported: created_at)

Example: created_atPossible values:

per_pageinteger · min: 1 · max: 50Optional

Number of records per page

Example: 10

pageinteger · min: 1Optional

Page number (starting from 1)

Example: 1

Responses

200

Credential receive states successfully loaded

application/json

400Error

application/json

404Error

application/json

500Error

application/json

get/wallets/{walletId}/receive

HTTPcURLJavaScriptPython

GET /wallets/{walletId}/receive HTTP/1.1
Host: zyfla-wallet-sandbox.meeco.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "states": [
    {
      "access_token": "text",
      "authorization_url": "text",
      "client_id": "text",
      "credential_id": "urn:uuid:4b5c8b6f-9b8a-4c8b-8b6f-9b8a4c8b6f9b",
      "credential_ids": [
        "urn:uuid:4b5c8b6f-9b8a-4c8b-8b6f-9b8a4c8b6f9b"
      ],
      "proofs": {
        "proof_type": "jwt",
        "jwt": [
          "text"
        ]
      },
      "credential_definition": {
        "vct": "text"
      },
      "credential_endpoint": "https://example.uri/credentials",
      "credential_offer": {
        "credential_issuer": "https://issuer.example.com",
        "credential_configuration_ids": [
          "text"
        ],
        "grants": {
          "authorization_code": {
            "issuer_state": "text"
          },
          "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
            "pre-authorized_code": "text",
            "tx_code": {
              "input_mode": "numeric",
              "length": 1,
              "description": "text"
            }
          }
        }
      },
      "credential_offer_uri": "https://example.com/credential_offer",
      "credential_offer_endpoint": "openid-credential-offer://credential_offer_uri=https://example.com/credential_offer",
      "did": "text",
      "format": "dc+sd-jwt",
      "kid": "text",
      "refresh_token": "text",
      "response_type": "code",
      "state": "e0d7bd1e-dce5-4366-989f-4647af68412a",
      "token_endpoint": "https://example.uri/token",
      "transaction_id": "text",
      "meta": {
        "created_at": "2024-01-09T12:00:00Z",
        "updated_at": "2024-01-09T12:00:00Z"
      }
    }
  ],
  "meta": {
    "order_by": "name",
    "order": "ASC",
    "order_from_params": true,
    "per_page": 10,
    "per_page_from_params": true,
    "records_count": 100,
    "page": 1,
    "page_count": 10
  }
}

Register credential offer

post

Credential offer is a JSON encoded object that the issuer uses to pass information to the wallet and initiate the issuance process. This endpoint is used to validate, parse and extract the necessary information, leading to the next step in the process, getting an access token.

For more information on the structure of the credential offer object, see section 4.1 in OpenID4VCI 1.0.

The three supported methods for registering a credential offer are:

• credential_offer: Pass the JSON object by value

• credential_offer_uri: Pass the JSON object by reference. The service performs a GET request to retrieve the object.

• credential_offer_endpoint - Credential Offer sent by the issuer to the wallet credential offer endpoint. It contains a single URI query parameter, either credential_offer or credential_offer_uri

Note that the options above are mutually exclusive.

After successfully registering the credential offer, a state is returned. This state is used as an identifier to link subsequent calls to receive endpoints.

Next Step

To continue the issuance process, call:

POST /wallets/{walletId}/receive/get_access_token

Authorizations

bearerAuthmutualTLS

AuthorizationstringOptional

Bearer authentication header of the form Bearer <token>.

Path parameters

walletIdstringRequired

Body

application/json

credential_offer_uristringOptionalExample: https://example.com/credential_offer

credential_offer_endpointstringOptionalExample: openid-credential-offer://credential_offer_uri=https://example.com/credential_offer

protocol_versionstring · enumOptional

version of credential issuance protocol. Defaults to openid4vci-v1

Possible values:

Responses

201

Successful registration of the credential offer.

application/json

credential_offer_uristringOptionalExample: https://example.com/credential_offer

credential_offer_endpointstringOptionalExample: openid-credential-offer://credential_offer_uri=https://example.com/credential_offer

statestringOptionalExample: e0d7bd1e-dce5-4366-989f-4647af68412a

400

Bad Request - The request was invalid or cannot be otherwise served.

application/json

post/wallets/{walletId}/receive

HTTPcURLJavaScriptPython

POST /wallets/{walletId}/receive HTTP/1.1
Host: zyfla-wallet-sandbox.meeco.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 531

{
  "credential_offer": {
    "credential_issuer": "https://issuer.example.com",
    "credential_configuration_ids": [
      "text"
    ],
    "grants": {
      "authorization_code": {
        "issuer_state": "text"
      },
      "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
        "pre-authorized_code": "text",
        "tx_code": {
          "input_mode": "numeric",
          "length": 1,
          "description": "text"
        }
      }
    }
  },
  "credential_offer_uri": "https://example.com/credential_offer",
  "credential_offer_endpoint": "openid-credential-offer://credential_offer_uri=https://example.com/credential_offer",
  "protocol_version": "openid4vci-v1"
}

{
  "credential_offer": {
    "credential_issuer": "https://issuer.example.com",
    "credential_configuration_ids": [
      "text"
    ],
    "grants": {
      "authorization_code": {
        "issuer_state": "text"
      },
      "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
        "pre-authorized_code": "text",
        "tx_code": {
          "input_mode": "numeric",
          "length": 1,
          "description": "text"
        }
      }
    }
  },
  "credential_offer_uri": "https://example.com/credential_offer",
  "credential_offer_endpoint": "openid-credential-offer://credential_offer_uri=https://example.com/credential_offer",
  "state": "e0d7bd1e-dce5-4366-989f-4647af68412a",
  "meta": {
    "created_at": "2024-01-09T12:00:00Z",
    "updated_at": "2024-01-09T12:00:00Z"
  }
}

Get access token

post

The get access token endpoint ensures the wallet is able to retrieve a valid access token to go to the next step of actually getting the credential(s).

Wallet initiated issuance

For wallet initiated issuance, this endpoint is the entry point. Only Authorization Code Flow is supported.

The following parameters are required:

• credential_issuer

• scope (must be able to be looked up from the credential issuer metadata credential_configurations_supported property)

• redirect_uri

• client_id

Issuer initiated issuance via credential offer

For issuer initiated issuance, the issuer communicates a credential offer that is registered before acquiring an access token.

Two flows that are supported are:

• Pre-Authorized Code Flow

• Authorization Code Flow

Authorization Code Flow

Uses the authorization_code as defined in RFC6749 to issue access tokens.

This is usually a two-step process, that involves authentication on the front channel (through a browser window) to be performed by the client.

In step 1, a call to this endpoint returns the authorization_url. This URL is what needs to be opened in a browser window and will authenticate the end-user to the service. This includes a redirect_uri responsible for receiving and storing the authorization_code.

In step 2, the service, exchanges the code for an access token by calling the Token Endpoint.

Pre-Authorized Code Flow

This flow is used when the issuer has already authenticated and authorized the end-user. The issuer provides a Pre-Authorized Code in the credential offer which is used to exchange it for an access token in the Token Endpoint. The Authorization Endpoint is not used in this flow.

For more information, see section 3.5 in OpenID4VCI 1.0.

Next Step

To continue the issuance process, call:

POST /wallets/{walletId}/receive/get_credential

Authorizations

bearerAuthmutualTLS

AuthorizationstringOptional

Bearer authentication header of the form Bearer <token>.

Path parameters

walletIdstringRequired

Body

application/json

authorization_codestringOptional

code claimed via authorization code flow. It can to be exchanged for the access token.

client_idstringOptional

Client identifier in OAuth 2.0

client_secretstringOptional

code_challengestringOptional

Part of PKCE, used when calling the authorization endpoint.

code_challenge_methodstringOptional

Part of PKCE, used when calling the authorization endpoint.

code_verifierstringOptional

Part of PKCE, used when calling the token endpoint, together with the authorization code

credential_issuerstringOptional

The URL of the Credential Issuer from which the Wallet is requested to obtain one or more Credentials. The authorization server is determined based on the Credential Issuer Metadata.

grant_typestring · enumOptionalPossible values:

issuer_statestringOptional

String value identifying a certain processing context at the Credential Issuer. This value is typically provided in the credential offer. When it is, the Wallet MUST send the value back to the Credential Issuer.

protocol_versionstring · enumOptional

version of credential issuance protocol. Defaults to openid4vci-v1

Possible values:

pre-authorized_codestringOptional

The code representing the authorization to obtain Credentials of a certain type. This parameter MUST be present if the grant_type is urn:ietf:params:oauth:grant-type:pre-authorized_code. Typically provided by the Credential Issuer in the credential offer.

redirect_uristringOptional

Only relevant when the grant_type is authorization_code.

scopestringOptional

Request credentials using OAuth 2.0 scope parameter

statestringOptional

tx_codestringOptional

String value containing a Transaction Code. This value MUST be present if a tx_code object was present in the Credential Offer (including if the object was empty). This parameter MUST only be used if the grant_type is urn:ietf:params:oauth:grant-type:pre-authorized_code.

Responses

201Success

application/json

access_tokenstringOptional

authorization_urlstringOptional

The URL to open in a browser in order to complete the authorization with the Authorization Server.

credential_definitionone ofOptional

or

client_idstringOptional

Client identifier in OAuth 2.0

refresh_tokenstringOptional

statestringOptional

404Error

application/json

post/wallets/{walletId}/receive/get_access_token

HTTPcURLJavaScriptPython

POST /wallets/{walletId}/receive/get_access_token HTTP/1.1
Host: zyfla-wallet-sandbox.meeco.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 457

{
  "authorization_code": "text",
  "authorization_details": [
    {
      "type": "openid_credential",
      "credential_configuration_id": "text"
    }
  ],
  "client_id": "text",
  "client_secret": "text",
  "code_challenge": "text",
  "code_challenge_method": "text",
  "code_verifier": "text",
  "credential_issuer": "text",
  "grant_type": "authorization_code",
  "issuer_state": "text",
  "protocol_version": "openid4vci-v1",
  "pre-authorized_code": "text",
  "redirect_uri": "text",
  "scope": "text",
  "state": "text",
  "tx_code": "text"
}

{
  "access_token": "text",
  "authorization_url": "text",
  "credential_definition": {
    "vct": "text"
  },
  "client_id": "text",
  "refresh_token": "text",
  "state": "text"
}

Get verifiable credential

post

Get credential from the issuer and perform key binding. A valid access token is required in order to call this endpoint.

See section 7 in OpenID4VCI 1.0 for more information.

Key Binding

Key binding is performed by providing either

• kid: Public key is presented. Should be used when credential format is dc+sd-jwt.

• did: DID is presented referencing one of the keys contained in the verificationMethod section of the DID document. Should be used when credential format is jwt_vc_json.

Only one of the kid or did parameters must be present during the request.

Both methods involve the wallet presenting key proof to the issuer to ensure control over cryptographic key material.

See section 7.2.1 in OpenID4VCI 1.0 for more information.

Not Supported Options

Note that the following are not supported by the endpoint

• transaction_id: Part of the deferred issuance flow, allows receiving a credential by referencing a transaction_id

• Receiving encrypted credentials

• legacy format header typ vc+sd-jwt

Authorizations

bearerAuthmutualTLS

AuthorizationstringOptional

Bearer authentication header of the form Bearer <token>.

Path parameters

walletIdstringRequired

Body

application/json

access_tokenstringOptional

credential_definitionone ofOptional

or

didstringOptional

kidstringOptional

statestringOptional

transaction_idstringOptional

A string identifying a Deferred Issuance transaction. This claim is contained in the response if the Credential Issuer was unable to immediately issue the Credential

Responses

201

New credential successfully added to the Wallet

application/json

idstringOptional

Internal reference to the credential record that later has to be used with other credential related endpoints

Example: 8293745e-f600-4fc6-ba1d-7827125a23e0

credentialstringOptional

Contains issued Credential. MUST be present when transaction_id is not returned. MAY be a string or an object, depending on the Credential format. See Appendix E for the Credential format specific encoding requirements.

credential_idstringOptional

Id under which the credential is stored in the wallet

Example: urn:uuid:4b5c8b6f-9b8a-4c8b-8b6f-9b8a4c8b6f9b

statestringRequired

transaction_idstringOptional

A string identifying a Deferred Issuance transaction. This claim is contained in the response if the Credential Issuer was unable to immediately issue the Credential

404Error

application/json

post/wallets/{walletId}/receive/get_credential

HTTPcURLJavaScriptPython

POST /wallets/{walletId}/receive/get_credential HTTP/1.1
Host: zyfla-wallet-sandbox.meeco.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "access_token": "text",
  "credential_definition": {
    "vct": "text"
  },
  "did": "text",
  "kid": "text",
  "state": "text",
  "transaction_id": "text"
}

{
  "id": "8293745e-f600-4fc6-ba1d-7827125a23e0",
  "credential": "text",
  "credential_id": "urn:uuid:4b5c8b6f-9b8a-4c8b-8b6f-9b8a4c8b6f9b",
  "state": "text",
  "transaction_id": "text"
}

Get credential receive state

get

Get credential receive state.

Authorizations

bearerAuthmutualTLS

AuthorizationstringOptional

Bearer authentication header of the form Bearer <token>.

Path parameters

walletIdstringRequired

statestringRequired

Responses

200

Credential receive state successfully loaded

application/json

access_tokenstringOptional

authorization_urlstringOptional

The URL to open in a browser in order to complete the authorization with the Authorization Server.

client_idstringOptional

Client identifier in OAuth 2.0

credential_idstringOptional

Id under which the credential is stored in the wallet

Example: urn:uuid:4b5c8b6f-9b8a-4c8b-8b6f-9b8a4c8b6f9b

credential_idsstring[]Optional

Credential Ids that were issued using this receive state

Example: urn:uuid:4b5c8b6f-9b8a-4c8b-8b6f-9b8a4c8b6f9b

credential_definitionone ofOptional

or

credential_endpointstringOptional

Credential Issuer credential endpoint called

Example: https://example.uri/credentials

credential_offer_uristringOptionalExample: https://example.com/credential_offer

credential_offer_endpointstringOptionalExample: openid-credential-offer://credential_offer_uri=https://example.com/credential_offer

didstringOptional

formatstring · enumOptionalPossible values:

kidstringOptional

refresh_tokenstringOptional

response_typestring · enumOptional

This value is always code

Possible values:

statestringOptionalExample: e0d7bd1e-dce5-4366-989f-4647af68412a

token_endpointstringOptional

Credential Issuer or Authorization Server token endpoint called

Example: https://example.uri/token

transaction_idstringOptional

A string identifying a Deferred Issuance transaction. This claim is contained in the response if the Credential Issuer was unable to immediately issue the Credential

404Error

application/json

500Error

application/json

get/wallets/{walletId}/receive/{state}

HTTPcURLJavaScriptPython

GET /wallets/{walletId}/receive/{state} HTTP/1.1
Host: zyfla-wallet-sandbox.meeco.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "access_token": "text",
  "authorization_url": "text",
  "client_id": "text",
  "credential_id": "urn:uuid:4b5c8b6f-9b8a-4c8b-8b6f-9b8a4c8b6f9b",
  "credential_ids": [
    "urn:uuid:4b5c8b6f-9b8a-4c8b-8b6f-9b8a4c8b6f9b"
  ],
  "proofs": {
    "proof_type": "jwt",
    "jwt": [
      "text"
    ]
  },
  "credential_definition": {
    "vct": "text"
  },
  "credential_endpoint": "https://example.uri/credentials",
  "credential_offer": {
    "credential_issuer": "https://issuer.example.com",
    "credential_configuration_ids": [
      "text"
    ],
    "grants": {
      "authorization_code": {
        "issuer_state": "text"
      },
      "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
        "pre-authorized_code": "text",
        "tx_code": {
          "input_mode": "numeric",
          "length": 1,
          "description": "text"
        }
      }
    }
  },
  "credential_offer_uri": "https://example.com/credential_offer",
  "credential_offer_endpoint": "openid-credential-offer://credential_offer_uri=https://example.com/credential_offer",
  "did": "text",
  "format": "dc+sd-jwt",
  "kid": "text",
  "refresh_token": "text",
  "response_type": "code",
  "state": "e0d7bd1e-dce5-4366-989f-4647af68412a",
  "token_endpoint": "https://example.uri/token",
  "transaction_id": "text",
  "meta": {
    "created_at": "2024-01-09T12:00:00Z",
    "updated_at": "2024-01-09T12:00:00Z"
  }
}

Delete receive credential state

delete

Delete state of a receive credential flow.

Authorizations

bearerAuthmutualTLS

AuthorizationstringOptional

Bearer authentication header of the form Bearer <token>.

Path parameters

walletIdstringRequired

statestringRequired

Responses

500Error

application/json

errorstring · enumRequired

Unique error identifier

Possible values:

extra_infoobjectRequired

Object that may contain more information about the error

messagestringRequired

User friendly error message

delete/wallets/{walletId}/receive/{state}

HTTPcURLJavaScriptPython

DELETE /wallets/{walletId}/receive/{state} HTTP/1.1
Host: zyfla-wallet-sandbox.meeco.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

500Error

{
  "error": "delete_receive_state_error",
  "extra_info": {},
  "message": "Error occurred while deleting receive credential state."
}

Handle holder receive callback

get

authorization_code redirect uri that was started via /receive endpoint. state and code come as a query parameters. code is exchanged for the access_token so client can call POST /wallets/{walletId}/receive/get_credential endpoint right away.

Query parameters

errorstringOptional

Error code

error_descriptionstringOptional

Error description

error_uristringOptional

Error URI

codestringOptional

Authorization code

statestringOptional

Authorization state

issstringOptional

Access token issuer

Responses

302

Issuer response captured and processed - redirect back to the client Wallet

No content

get/wallets/receive/callback

HTTPcURLJavaScriptPython

GET /wallets/receive/callback HTTP/1.1
Host: zyfla-wallet-sandbox.meeco.cloud
Accept: */*

302

Issuer response captured and processed - redirect back to the client Wallet

No content