Issuing verifiable credentials

The credential issuance process involves the customer application, the customers OAuth2 server, Partisia's credential issuance service, and the holder's wallet, each with a specific role in enabling credential issuance.

The credential issuance service handles the specifics of issuing a credential through the pre-authorized flow. Your application remains responsible for starting the process of issuing a verifiable credential with the credential issuance service.

This section describes the communication flows and configuration requirements for initiating the verifiable credential issuance as well as the reception of the issuance results from the credential issuance service.

1-3. User authentication

The process begins when the holder logins to your application, usually through a website or a mobile app.

4. Start interaction

The issuance process usually begins when the holder interacts with your application, usually by clicking a button or navigating to a specific page. The application recognizes the holder's input and responds, initiating the engagement.

5. Application starts issuance

Your application initiates the issuance process by sending an API POST request to the credential issuance service. To create a new request you must provide a pre-authorized code, that the wallet can use with the OAuth server to obtain an access token, as an input. Additionally, you must provide the data-set to be used in the issued credential.

This initial request signals the credential issuance service to prepare for the interaction with the wallet. For example:

Example

curl -X 'POST' \
'http://localhost:8079/issuance/oid4vci/new-session' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "pre-authorized_code": "SCY7DQRYUWeOg3fNjK4AjQ",
    "credential_dataset": {
        "first_name": "Jens",
        "last_name": "Jensen",
        "id_number": 12345678
    }
}'

Once the credential issuance service receives the POST request, it creates a new issuance session. The returned credential_offer_uri is later used by the wallet to interact with the correct issuance session.

6. Credential issuance service returns issuance session info

Once the issuance session is set up, the credential issuance service responds to the initial POST request with a credential offer URI. This response from the credential issuance service also includes the session ID. For example:

{
    "session_id": "7d4633b273f000ca2243e258863975907756b3afc29783c7777cf47839264722",
    "credential_offer_uri": "http://localhost:8079/issuance/oid4vci/credential-offer/7d4633b273f000ca2243e258863975907756b3afc29783c7777cf47839264722"
}

7. Application forwards credential offer URI to wallet

After receiving a response from the credential issuance service, your application must forward the credential offer URI to the holder's wallet. This can be achieved through various methods, such as generating a QR code for the user to scan with their wallet, or sending the URI via email or another communication channel.

The customer application is responsible for ensuring the URI is shared in a format supported by the wallet. Misalignment here—such as using a communication method the wallet does not recognize—can disrupt the issuance flow.

8. Issuance Black Box

The following steps are carried out by Partisia's credential issuance service, which carry out the rest of the OID4VCI protocol. If you have configured your application correctly, the results will be pushed to the correct endpoint in your application (see next point).

In short, the credential issuance service issues the verifiable credential to the holder's wallet and ensures the wallet receives the correct information and is bound to the credential through cryptographic signatures. See a detailed explanation of the issuance flow here.

9. Credential issuance service pushes results to application

Once the credential is issued, the credential issuance service sends the verifiable credential to the application via a POST request to a pre-configured endpoint.

The customer application must ensure its application endpoint is correctly configured and that the credential issuance service is configured to send the data to that endpoint. If the endpoint is missing or misconfigured, the result cannot be delivered. Upon receiving the data, the customer application can process the information as needed.

Here's an example a POST request sent by the credential issuance service:

Example

curl -X 'POST' \
  'http://localhost:8083/issuance/issued-credential' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 5I90CwXlZoolopOSplVBOoV63qXSTEo4piJKJ0iizFau79HU6viEvzgGReWycN8V' \
  -d '{
  "session_id": "7d4633b273f000ca2243e258863975907756b3afc29783c7777cf47839264722",
  "credential_response": {
    "credentials": [
      {
        "credential": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRlbnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eURlZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLzU2NTA0OSIsImlzc3VhbmNlRGF0ZSI6IjIwMTAtMDEtMDFUMDA6MDA6MDBaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJkZWdyZWUiOnsidHlwZSI6IkJhY2hlbG9yRGVncmVlIiwibmFtZSI6IkJhY2hlbG9yIG9mIFNjaWVuY2UgYW5kIEFydHMifX19LCJpc3MiOiJodHRwczovL2V4YW1wbGUuZWR1L2lzc3VlcnMvNTY1MDQ5IiwibmJmIjoxMjYyMzA0MDAwLCJqdGkiOiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVudGlhbHMvMzczMiIsInN1YiI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSJ9.z5vgMTK1nfizNCg5N-niCOL3WUIAL7nXy-nGhDZYO_-PNGeE-0djCpWAMH8fD8eWSID5PfkPBYkx_dfLJnQ7NA"
      }
    ]
  }
}'