Skip to main content

Issue credentials (Connectionless)

In the Identus Platform, the Issue Credentials Protocol allows you to create, retrieve, and manage issued verifiable credentials (VCs) between a VC issuer and a VC holder.

Roles​

In the Issue Credentials Protocol, there are two roles:

  1. The Issuer is responsible for creating a new credential offer, sending it to a Holder, and issuing the VC once the offer is accepted.
  2. The Holder is responsible for accepting a credential offer from an issuer and receiving the VC.

The Issuer and Holder interact with the Identus Cloud Agent API to perform the operations defined in the protocol.

Prerequisites​

Before using the "Connectionless" Issuing Credentials protocol, the following conditions must be present:

  1. Issuer Cloud Agents is up and running
  2. The Issuer has a published PRISM DID, and the DID document must have at least one assertionMethod key for issuing credentials (see Create DID and Publish DID)
  3. The Holder is either another Cloud Agent or Edge Agent SDK

Overview​

The protocol described is a VC issuance process between an Issuer (Identus Cloud Agent) and Holder (Identus Edge Agent SDK).

The protocol consists of the following main parts:

  1. The Issuer creates a new credential offer using the /issue-credentials/credential-offers/invitation endpoint, which includes information such as the schema identifier and claims. This returns a unique OOB (out-of-band) invitate code for the prospective Holder.
  2. The Holder accepts the OOB invite (see SDK acceptInvitation)
  3. The Issuer responds by sending the actual Credential Offer
  4. The Holder accepts the Credential Offer
  5. The Issuer sends the Verifiable Credential

The claims provide specific information about the individual, such as their name or qualifications.

This protocol is applicable in various real-life scenarios, such as educational credentialing, employment verification, and more. In these scenarios, the Issuer could be a school, an employer, etc., and the Holder could be a student or an employee. The VCs issued during this protocol could represent a diploma, a certificate of employment, etc.

Endpoints​

EndpointDescriptionRole
/issue-credentials/credential-offers/invitationThis endpoint allows you to create a new credential offer invitationIssuer
/issue-credentials/credential-offers/accept-invitationThis endpoint allows you to accept the invitationHolder
/issue-credentials/recordsThis endpoint allows you to retrieve a collection of all the existing credential recordsIssuer, Holder
/issue-credentials/records/{recordId}This endpoint allows you to retrieve a specific credential record by its idIssuer, Holder
/issue-credentials/records/{recordId}/accept-offerThis endpoint allows you to accept a credential offerHolder
/issue-credentials/records/{recordId}/issue-credentialThis endpoint allows you to issue a VC for a specific credential record.Issuer
info

Please check the full Cloud Agent API specification for more detailed information.

Issuer interactions​

This section describes the Issuer role's available interactions with the Cloud Agent.

Creating a Credential Offer​

To start the process, the issuer needs to create a credential offer invitation. To do this, make a POST request to the /issue-credentials/credential-offers/invitation endpoint with a JSON payload that includes the following information:

  1. claims: The data stored in a verifiable credential. Claims get expressed in a key-value format. The claims contain the data that the issuer attests to, such as name, address, date of birth, and so on.
  2. issuingDID: The DID referring to the issuer to issue this credential from
  3. schemaId: An optional field that, if specified, contains a valid URL to an existing VC schema. The Cloud Agent must be able to dereference the specified URL (i.e. fetch the VC schema content from it), in order to validate the provided claims against it. When not specified, the claims fields is not validated and can be any valid JSON object. Please refer to the Create VC schema doc for details on how to create a VC schema.
  4. credentialFormat: The format of the credential that will be issued - JWT in this case. When not specified, the default value is JWT.
note

The issuingDID property comes from completing the pre-requisite steps listed above

Once the request initiates, a new credential record for the issuer gets created with a unique ID. The state of this record is now OfferPending.

# Issuer POST request to create a new credential offer
curl -X 'POST' \
  'http://localhost:8080/cloud-agent/issue-credentials/credential-offers/invitation' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H "apikey: $API_KEY" \
    -d '{
          "claims": {
            "emailAddress": "alice@wonderland.com",
            "givenName": "Alice",
            "familyName": "Wonderland",
            "dateOfIssuance": "2020-11-13T20:20:39+00:00",
            "drivingLicenseID": "12345",
            "drivingClass": 3
          },
          "credentialFormat": "JWT",
          "issuingDID": "did:prism:9f847f8bbb66c112f71d08ab39930d468ccbfe1e0e1d002be53d46c431212c26",
          "schemaId": "http://localhost:8080/cloud-agent/schema-registry/schemas/3f86a73f-5b78-39c7-af77-0c16123fa9c2"
        }'

Sending the Offer to the Holder​

The next step for the Issuer is to send the OOB invite Holder (by definition, this is "out of band", so not handled by Identus). Common ways to convey such OOB invites might be a QR code that is scanned, or via an existing channel of connection in an application.

Issuing the Credential​

Once the holder has approved the offer and sent a request to the Issuer, the Issuer will receive the request via DIDComm and update the record state to RequestReceived.

The Issuer can then use the /issue-credentials/records/{recordId}/issue-credential endpoint to issue the credential to the holder.

# Issuer POST request to issue the credential
# make sure you have `issuer_record_id` extracted from created credential offer
# and the record achieved `RequestReceived` state
curl -X POST \
    "http://localhost:8080/cloud-agent/issue-credentials/records/$issuer_record_id/issue-credential" \
    -H "Content-Type: application/json" \
    -H "apikey: $API_KEY"

When this endpoint gets called, the state of the record will change to CredentialPending, and after processing, it will change to CredentialGenerated.

Finally, the Issuer agent will send the credential to the holder via DIDComm, and the state of the record will change to CredentialSent. At this point, the Issuer's interactions with the holder are complete.

Holder interactions​

This section describes the Holder role's available interactions with the Cloud Agent.

Receiving the VC Offer​

The Holder will receive the offer from the Issuer via DIDComm, and a new credential record with a unique ID gets created in the OfferReceived state.

This process is automatic for the Cloud Agent.

You could check if a new credential offer is available using /issue-credentials/records request and check for any records available in OfferReceived state:

# Holder GET request to retrieve credential records
curl "http://localhost:8090/cloud-agent/issue-credentials/records" \
    -H "Content-Type: application/json" \
    -H "apikey: $API_KEY"

Approving the VC Offer​

To accept the offer, the Holder can make a POST request to the /issue-credentials/records/{recordId}/accept-offer endpoint with a JSON payload that includes the following information:

  1. holder_record_id: The unique identifier of the issue credential record known by the holder's Cloud Agent.
  2. subjectId: This field represents the unique identifier for the subject of the verifiable credential. It is a short-form PRISM DID string, such as did:prism:subjectIdentifier.
# Holder POST request to accept the credential offer
curl -X POST "http://localhost:8090/cloud-agent/issue-credentials/records/$holder_record_id/accept-offer" \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H "apikey: $API_KEY" \
    -d '{
          "subjectId": "did:prism:subjectIdentifier"
     }'

This request will change the state of the record to RequestPending.

Receiving the VC Credential​

Once the Holder has approved the offer and sent a request to the Issuer, the Holder agent will process the request and send it to the Issuer agent. The state of the Holder's record will change to RequestSent.

After the Issuer has issued the credential, the Holder will receive the credential via DIDComm, and the state of the Holder's record will change to CredentialReceived. This process is automatic for the Cloud Agent.

The Holder can check the achieved credential using a GET request to /issue-credentials/records/{recordId}/ endpoint.

Sequence diagram​

TODO