Caro logo

Credential exchanges are symbolized by the following entities, which are tied to the wallet:

  • credential acquisitions symbolize the state of the issuance on the holder wallet - the receiver of the credential - during an issuance exchange
  • credential issuances symbolize the state of the issuance on the issuer wallet - the issuer of the credential - during an issuance exchange

These entities can be used to keep track of ongoing exchanges for a wallet

Note: Viewing the state of the exchanges can be done by calling their respective endpoints

Issuance: Holder initiates the Exchange

Example: An OEM is requesting a GHG Report from RCS - the Holder is the OEM and the issuer is RCS. The template is the GHG Report template and the actual signed report is the credential

In this scenario, the holder initiates the wallet exchange by requesting a credential from an issuer.

Issuance flow when the holder initiates the exchange

Issuance flow when the holder initiates the exchange

1 - Holder creates and sends a credential acquisition

The exchange can be initiated by creating a credential acquisition for the holder wallet using the following endpoint:

POST: {{host}}/credential-acquisitions/?organizationId={{organizationId}}
DATA:
{
    "walletId": "<string - holder wallet UUID>",
    "templateId": "<string - template UUID of the requested credential>",
    "issuer": "<string - issuer DID (Identifier)>",
    "holder": "<string - holder DID (Identifier) - has to belong the holder wallet>",
    "credentialUri": "<string - credential uri of the to be created credential (appears in the credential as credentialID)>",
    "data": { // credential subject: attribute data of the credential as key pair values - as defined by the template
        "<key>": "<value>",
        "<key>": "<value>"
        "<key>": "<value>"
    }
}

Note: The created credential acquisition is in state Created

Creating a credential acquisition triggers an exchange which notifies the receiver (the issuer).

Note: Notifying the issuer changes the state of the credential acquisition to Pending

2 - Issuer accepts or declines a credential issuance

Upon reception of the credential acquisition, a credential issuance is created on the issuer wallet

Note: The created credential issuance is in state Received

This credential issuance can be Accepted or Declined using the following endpoint:

PUT: {{host}}/credential-issuances/{{credentialIssuanceId}}?organizationId={{organizationId}}
DATA:
{
    "state": "<either: Accepted or Declined>",
    "data": { // Optional - data to be used for the credential subject
            "resultsOfTestsreports": "Nope"
        }
}

Note: The credential issuance data is initialized with the data received by the holder (credential acquisition data) - this data can be overwritten by the issuer

If the state of the credential issuance is updated to Accepted, the wallet issues a credential and signs it - the content (credential subject) of the credential is defined by the data attribute of the credential issuance. The credential is then stored in the data attribute of the credential issuance and the state of the credential issuance is changed to Issued . This triggers the exchange to continue and the credential issuance is sent to the holder.

If the If the state of the credential issuance is updated to Declined, the holder is notified and the exchange ends.

3.1 - Holder receives the credential issuance - state: Issued

When the holder receives the credential issuance, the corresponding credential acquisition is updated. If the credential issuance is in state Issued , the state of the credential acquisition is updated to Received and holder is then free to review the credential and change the state to Accepted or Refused using the update endpoint:

PUT: {{host}}/credential-acquisition/{{credentialacquisitionId}}?organizationId={{organizationId}}
DATA:
{
    "state": "<either: Accepted or Refused>",
}

If the state of the credential acquisition is updated to Accepted , the credential is stored in the holder wallet.

If the state of the credential acquisition is updated to Refused , the credential is ignored and the exchange ends.

3.1 - Holder receives the credential issuance - state: Declined

If the state of the received credential issuance is Declined, the credential acquisition is updated accordingly and the state is changed to Declined

Issuance: Issuer initiates the Exchange

Example: RCS issues audit reports for a supplier - RCS is the Issuer and the supplier is the Holder

Issuance flow when the Issuer initiates the exchange

Issuance flow when the Issuer initiates the exchange

1 - Issuer creates and sends a credential issuance

The issuer initiates the exchange by created a credential issuance for his/her wallet ****using the following endpoint:

PUT: {{host}}/credential-issuances?organizationId={{organizationId}}
DATA:
DATA:
{
    "walletId": "<string - issuer wallet UUID>",
    "templateId": "<string - template UUID of the to be issued credential>",
    "issuer": "<string - issuer DID (Identifier) - has to belong the issuer wallet>",
    "holder": "<string - holder DID (Identifier)>",
    "credentialUri": "<string - credential uri of the to be created credential (appears in the credential as credentialID)>",
    "data": { // credential subject: attribute data of the credential as key pair values - as defined by the template
        "<key>": "<value>",
        "<key>": "<value>"
        "<key>": "<value>"
    }
}

Note: The created credential issuance is in state Accepted

This triggers the issuance of the credential by the issuer wallet. The state of the credential issuance is then updated to Issued and the credential issuance is sent to the holder.

2 - Holder receives the credential issuance and accepts or refuses it

When the holder receives the credential issuance, the corresponding credential acquisition is updated. Since the credential issuance is in state Issued , the state of the credential acquisition is updated to Received and holder is then free to review the credential and change the state to Accepted or Refused using the update endpoint:

PUT: {{host}}/credential-acquisition/{{credentialacquisitionId}}?organizationId={{organizationId}}
DATA:
{
    "state": "<either: Accepted or Refused>",
}

If the state of the credential acquisition is updated to Accepted , the credential is stored in the holder wallet.

If the state of the credential acquisition is updated to Refused , the credential is ignored and the exchange ends.

Note: for credential acquisition states: Declined means that the issuer declined to issue the credential and Refused means that the holder refused to store the received credential

Was this page helpful?