Issue credentials

Verifiable credentials, once issued, belong to the recipient. They contain issued proof of certain attributes that can be presented to a verifying party at a later date. Like showing a drivers license to prove your age in person, the recipients of a credential can show their digital proofs to prove information digitally.

This guide contains everything you need to know about issuing credentials with Paradym. It will show you how to to:

Initial Considerations
Create a Credential Template
Issue a Credential
View Issued Credentials

Let’s get started! 🚀

Initial Considerations

Before creating a credential template, there are a few things to consider. The first step is to choose which format of credential you want to issue. Each format has its own characteristics, and can influence factors such as available features, security, privacy and efficiency. In addition, the credential format also influences the exchange protocol that is used during issuance:

SD-JWT VC mDoc Support OpenID4VC Issuance .
SD-JWT VC Support Direct SD-JWT VC Issuance (no exchange protocol).
AnonCreds Support DIDComm Issuance .

Knowing the format you want to issue also affects what kind of issuer you can use. Paradym supports issuing credentials with either a DID or with a X.509 certificate. X.509 certificates must be created before defining the credential template.

AnonCreds SD-JWT VC Support did:web, did:cheqd:testnet or did:cheqd:mainnet
SD-JWT VC mDoc Support X.509 Certificates.

💡

Paradym supports two optional external integrations during the issuance process when using OpenID4VC Issuance : Authorization Server and Attribute Providers.

We recommend reading through the introduction of those pages in order to see if that is something you’re interested in. Configuring those is optional and can be changed after creating a credential template.

Create a Credential Template

Now that you have already chosen which format and issuer to use, it’s time to create a credential template. A credential template defines the characteristics of your credential, as well as the attributes it will contain. Once created, a template can be used to issue as many credentials as you want.

💡

A credential template does not contain the values of attributes (such as the first name “John”), just the general schematics and structure of the credential, it is not linked to any specific person or personal information.

When creating a credential template, there are a few things you will need to know:

The format and issuer of the credential.
The type of the credential you want to issue.
The attributes your credential will include.
The validity of your credential.
Optionally, branding and external integrations.

Creating your first credential template is easiest to do within the dashboard. It gives you a preview of the credential branding, and guides you through configuring the attributes of the credential. However, if you’ve set up a credential template multiple times already, it might be beneficial to create a credential template using the API.

The easiest way to get started with the API is using the interactive API Reference . If you would like to follow along using a custom API client, make sure follow the Quickstart guide. You can read more on interacting with the API.

SD-JWT VC

To create an SD-JWT VC credential template in the API we will make a POST request to https://api.paradym.id/v1/projects/{projectId}/templates/credentials/sd-jwt-vc. For detailed information on the endpoint, refer to the create sd-jwt-vc credential template in the API reference.


{
  "name": "My SD-JWT VC template",
  "description": "This is a description",
  "background": {
    "color": "#FFFFFF",
    "url": "https://example.com/image.png"
  },
  "text": {
    "color": "#000000"
  },
  "type": "UniversityCard",
  "attributes": {
    "first_name": {
      "type": "string",
      "name": "First Name",
      "description": "First name must always be disclosed and is required",
      "required": true,
      "alwaysDisclosed": true
    },
    "last_name": {
      "type": "string",
      "name": "Last Name",
      "description": "Last name does not always have to be disclosed and is optional",
      "required": false,
      "alwaysDisclosed": false
    }
  }
}

mDOC

To create an mDoc credential template in the API we will make a POST request to https://api.paradym.id/v1/projects/{projectId}/templates/credentials/mdoc. For detailed information on the endpoint, refer to the create mdoc credential template in the API reference.


{
  "name": "My mDoc template",
  "description": "This is a description",
  "background": {
    "color": "#FFFFFF",
    "url": "https://example.com/image.png"
  },
  "text": {
    "color": "#000000"
  },
  "type": "org.example.UniversityDoc",
  "attributes": {
    "org.example.UniversityDoc": {
      "first_name": {
        "type": "string",
        "name": "First Name",
        "description": "First name must always be disclosed and is required",
        "required": true,
        "alwaysDisclosed": true
      },
      "last_name": {
        "type": "string",
        "name": "Last Name",
        "description": "Last name does not always have to be disclosed and is optional",
        "required": false,
        "alwaysDisclosed": false
      }
    }
  }
}

AnonCreds

It is not possible at the moment to update an AnonCreds template because the schema and credential definition generated are static. Instead to make changes to an AnonCreds credential template, a new template needs to be created.

To create an AnonCreds credential template in the API we will make a POST request to https://api.paradym.id/v1/projects/{projectId}/templates/credentials/anoncreds. For detailed information on the endpoint, refer to the create anoncreds credential template in the API reference.

The AnonCreds credential template is similar in structure to the other credential templates, but has a few limitations:

Branding (text and background) are not supported.
Only string and number attribute types are supported
For attribute properties alwaysDisclosed is not supported, as AnonCreds credential cannot influence which fields the holder MUST disclose.
For attribute properties required is not supported. All attributes MUST be included in the credential. This is a limitation of the AnonCreds credential format. A fake value (such as ""/“null” or 0) could be used if there is no value.
The schema property is used instead of the type property and is not required.

💡

When no schema is provided, Paradym will create a schema for you and host this along with your DID. You can provide an existing schema as the schema property to create the credential template based on the existing schema (whether created inside or outside Paradym). In this case the attributes MUST exactly match those of the existing schema, and schema network (did:web, did:cheqd:testnet or did:cheqd:mainnet) MUST match the issuer identifier (did:web by default).


{
  "name": "My AnonCreds template",
  "description": "This is a description",
  "attributes": {
    "first_name": {
      "type": "string",
      "name": "First Name",
      "description": "First name is required"
    },
    "last_name": {
      "type": "string",
      "name": "Last Name",
      "description": "Last name is optional"
    }
  }
}

For all template formats, the return value will be approximately the same as the payload you provided, with a few extra fields (such as id, createdAt and format) added. The type you provided has been transformed into an URL in the case of SD-JWT VC and AnonCreds credentials.

In the Dashboard you can create a credential template either from the Overview or the Templates tabs. Creating a new template will bring you to the template builder, which will guide through all the required configuration.

In the template builder, you define certain characteristics of your credential. These are the same fields as you define over the API, and can be divided into three general topics.

General Settings

The general settings of your credential can impact functionality and interoperability and require some level of technical knowledge. After all, credentials belong to the recipient (once issued) who might use them for a variety of situations. The exchange of verifiable credentials on a technical level is determined by certain standards and protocols. An identity wallet supporting one set of standards might not be able to accept credentials that adhere to a different set of standards.

Here, you need to define:

The name and description of the credential, visible in the user’s wallet. For SD-JWT VC and mDoc templates you can provide localized names and descriptions in multiple languages. Learn more about localization.
The format and issuer of the credential, chosen on the previous step.
SD-JWT VC mDOC The type of the credential is a unique and reusable identifier. This identifier can be used during a presentation request to request a credential of this specific type.
SD-JWT VC AnonCreds Whether or not you want to be able to revoke this credential later.

💡

SD-JWT VC Paradym creates a unique URL based on the defined credential type. This way, in the future, unique credential types can more easily be used and shared.

Attributes

The actual content of your credential template is defined in the attributes. This is where you can add information fields to the credential and define their technical properties. For example, the credential ‘Drivers License’, might contain attributes such as First Name, Last Name, Date of Birth, Place of Registration and Vehicle Type.

An attribute is made up out of a name and description, but has some additions that influence functionality.

The attribute key can be used to request the credential information programmatically (e.g. someone could request the value of dateOfBirth).
The attribute type can also be used in proof requests to specify the request (e.g. someone could request the value of vehicleType only if it is a string type).
SD-JWT VC mDoc The required field determines if a credential attribute is required for issuance (e.g. you could not issue a drivers license without the field placeOfRegistration). This field enables you to restrict on the template level, the way credentials are issued in practice.
SD-JWT VC The always disclosed field determines if a credential attribute will always be shared with the verifier in a proof request. You can use this field to make sure that certain information is always shared with a verifying party (e.g. any proof request concerning the drivers license must always return the placeOfRegistration).
SD-JWT VC mDoc You can provide localized names for attributes in multiple languages. This allows wallets to automatically display credentials in the user’s preferred language. Learn more about localization.

Creating a good credential template is easier with a specific use case in mind, because the restrictions will be clear. However, it can be important to consider what the credential might also be used for in creating the template. For example, a drivers license could prove driving ability as well as someone’s name or age.

SD-JWT VC mDoc Appearance

The look and feel of your credential as it appears in a recipients identity wallet. Here, you can change the branding and styling elements, like your background and text colors, as well as using a background image to make your credential standout. The credential will always show your profile logo and profile name. These can be defined in the settings and will be the same for all credentials you issue.

SD-JWT VC mDoc Validity

The validity of the credential. For SD-JWT VC, you can specify from which date the credential is valid and until which date the credential will be valid. The latter can either be a fixed date, or a number of months, days or years in the future. For mDoc, all credentials are valid from the moment of issuance up to a certain number of months or days in the future.

The validity settings are also limited by the issuer you chose. When using an X.509 certificate as issuer, you can only have a credential that is valid during the lifetime of the certificate itself. We help you with this by ensuring that you cannot create a credential template that is valid for a longer period that the certificate itself.

SD-JWT VC mDoc External Integrations

The external integrations are optional. Here you configure authorization servers and attribute providers. For more information on how to configure and use those, refer to their dedicated documentation pages: Authorization Servers and Attribute Providers.

After filling out all the sections you can create your credential template! 🚀 Once created it will appear in your credential overview and can be used to issue credentials.

Issue a Credential

The Paradym API currently supports issuing and verifying SD-JWT VCs and mDoc credentials over OpenID4VC, as well as issuing and verifying AnonCreds credentials over DIDComm. Read more about the different standards and protocols.

Based on the credential format you selected in the credential template you should choose the issuance flow:

SD-JWT VC Use OpenID4VC Issuance or Direct SD-JWT VC Issuance .
mDoc Use OpenID4VC Issuance .
AnonCreds Use DIDComm Issuance .

OpenID4VC API

If you created your credential template using the dashboard, make sure to get yourself familiar with the API Reference . If you would like to follow along using a custom API client, make sure follow the Quickstart guide. You can read more on interacting with the API.

To issue an SD-JWT VC or mDoc credential using OpenID4VCI based on the created template, make a POST request to https://api.paradym.id/v1/projects/{projectId}/openid4vc/issuance/offer. For detailed information on the endpoint, refer to create OpenID4VC credential offer in the API reference.

In the payload below, we create a credential offer containing one credential, based on the credential template we created earlier. Make sure to update the attributes object to match with the keys of the credential template, and update the credentialTemplateId to the ID of the credential template. The keys in the attributes object must match with the keys you provided when creating the credential template.


{
  "credentials": [
    {
      "credentialTemplateId": "clu921ps300047eghxvhz33m4",
      "attributes": {
        "firstName": "John",
        "lastName": "Doe"
      }
    }
  ]
}

The payload that is returned will look as follows:


{
  "id": "clv168twg000227kynam8v96w",
  "createdAt": "2024-04-15T16:30:54.304Z",
  "updatedAt": "2024-04-15T16:30:54.304Z",
  "projectId": "cluo51f8c000kp0dwmk33uzaj",
  "status": "offered",
  "error": null,
  "offerUri": "https://paradym.id/invitation?credential_offer_uri=https%3A%2F%2Fparadym.id%2Finvitation%2F7d7628cc-8221-4783-a5ce-f0f2b335361f%2Foffers%2Fe5fade58-5145-4b9b-a3bd-7428fbc995b2%3Fraw%3Dtrue",
  "credentials": [
    {
      "credentialTemplateId": "clu921ps300047eghxvhz33m4",
      "status": "offered"
    }
  ]
}

The offerUri contains an OpenID4VC issuance invitation url which you can open in the browser and it will render a QR code which you can scan with the Paradym Wallet.

You can use webhooks to get notified of changes in the credential issuance session.

DIDComm API

To issue an AnonCreds credential using DIDComm based on the created template, we will make a POST request to https://api.paradym.id/v1/projects/{projectId}/didcomm/issuance/offer. For detailed information on the endpoint, refer to create DIDComm issuance offer in the API reference.

In the payload below we create a credential offer containing one credential, based on the credential template we created earlier. Make sure to update the attributes object to match with the keys of the credential template, and update the credentialTemplateId to the ID of the credential template. The keys in the attributes object must match with the keys you provided when creating the credential template.


{
  "didcommInvitation": {
    "createConnection": true,
  },
  "credential": {
    "credentialTemplateId": "clu921ps300047eghxvhz33m4",
    "attributes": {
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

The payload that is returned will look as follows:


{
  "didcommInvitation": {
    "id": "clxeizl1p00kfo7sn9to5d4cl",
    "status": "active",
    "invitationUri": "https://paradym.id/invitation/f927bd5a-9f88-493c-8417-65cb3830097f",
    "reusable": false,
    "createdAt": "2024-06-14T10:08:02.893Z",
    "updatedAt": "2024-06-14T10:08:02.893Z"
  },
  "didcommIssuance": {
    "id": "clu6p64z80001a5muhvp2uvpy",
    "status": "offered",
    "credential": {
      "id": "clwd3ru0s000008l4bh7w2kit",
      "credentialTemplateId": "clu921ps300047eghxvhz33m4",
      "status": "offered",
      "exchange": "didcomm",
      "format": "anoncreds",
      "revocable": false
    },
    "createdAt": "2023-01-03T00:00:00.000Z",
    "updatedAt": "2023-01-03T00:00:00.000Z",
    "error": null
  }
}

Directly sending a credential offer to a connection

By passing didcommInvitation we will create an invitation that can be shared (as a QR code) with the intended recipient of the credential offer. If you’ve already interacted with the recipient in the past, you can also provide a didcommConnectionId instead of didcommInvitation. This will directly send the credential offer to the wallet of the holder. You can find connections associated with a previous invitation in the Retrieve DIDComm Connections endpoint and filtering using the filter[didcommInvitationId]=<didcommInvitationId> query.

You can use webhooks to get notified of changes in the credential issuance session.

Direct SD-JWT VC Issuance API

Direct issuance is intended for more advanced flows, or where the credential does not have to be sent to an external wallet. No exchange protocol is used, and the SD-JWT VC is directly signed and returned in the API.

SD-JWT VCs issued using OpenID4VC are always bound to a DID that is controlled by the external wallet of the holder. When using direct issuance it is currently not supproted to provide the DID the credential should be bound to, and so the SD-JWT VC will not be bound to any DID and will act as a bearer credential.

To directly issue an sd-jwt-vc credential without exchange protocol based on the created template, we will make a POST request to https://api.paradym.id/v1/projects/{projectId}/issuance/sd-jwt-vc. For detailed information on the endpoint, refer to Direct SD-JWT VC Issuance

In the payload below we issue an sd-jwt-vc credential, based on the credential template we created earlier. Make sure to update the attributes object to match with the keys of the credential template, and update the credentialTemplateId to the ID of the credential template. The keys in the attributes object must match with the keys you provided when creating the credential template.


{
  "credentialTemplateId": "clu921ps300047eghxvhz33m4",
  "attributes": {
    "first_name": "John",
    "last_name": "Doe"
  }
}

The payload that is returned will look as follows:


{
  "credential": {
    "id": "clwd3q1j8000008jzcworgqon",
    "credentialTemplateId": "clu921ps300047eghxvhz33m4",
    "format": "sd-jwt-vc",
    "status": "issued",
    "revocable": false
  },
  "sdJwtVc": {
    "encoded": "ey...",
    "decoded": {
      "vct": "https://metadata.paradym.id/types/134123-example",
      "iss": "did:web:metadata.paradym.id:a532849a-9790-4faa-a75b-b3d59d3094cc"
    }
  }
}

The credential contains metadata about the issued credential, while the sdJwtVc contains the actual sd-jwt-vc in encoded and decoded format. You can paste the encoded value in the Paradym SD-JWT VC debugger to learn more about the issued credential.

You can use webhooks to get notified of changes in the credential issuance session.

View Issued Credentials

OpenID4VC Issuance Sessions You can retrieve all your OpenID4VC issuance sessions by making a GET request to https://api.paradym.id/v1/projects/{projectId}/openid4vc/issuance. For detailed information on the endpoint, refer to retrieve OpenID4VC issuance sessions in the API reference.

DIDComm Issuance Sessions You can retrieve all your DIDComm issuance sessions by making a GET request to https://api.paradym.id/v1/projects/{projectId}/didcomm/issuance. For detailed information on the endpoint, refer to retrieve DIDComm issuance sessions in the API reference.

Issued Credentials Metadata about all issued credentials can be retrieved by making a GET request to https://api.paradym.id/v1/projects/{projectId}/issuance. For detailed information on the endpoint, refer to retrieve issued credentials in the API reference. This endpoint is mostly relevant for revoking previously issued credentials.

That’s it! 🚀

That concludes this guide. You now know how to:

Create a credential template
Use a credential template to issue a credential
View your issued credentials

If you have any suggestions, remarks or questions, join the Paradym Community and let us know. Happy building!