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:

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

Let's get started! 🚀

Create a credential template

To issue credentials in your solution you'll first need to create a credential template. A credential template defines the characteristics of your credential, as well as the attributes that 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 individual information, just the general schematics of the credential, it is not linked to any specific person or personal information.

When creating your credential template you are basically making the blueprint that all your credentials of that type will follow. The key things you need to know before creating a template are:

The type of credential you want to issue (currently the API only supports SD-JWT credentials)
The attributes your credential needs to have
[Optional] The branding you'd like to add

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 (opens in a new tab). 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 create a 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 (opens in a new tab) 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
    }
  }
}

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.

Use a credential template to issue a credential

The Paradym API currently supports issuing and verifying SD-JWT credentials over OpenID4VC. Read more about the different standards and protocols.

If you created your credential template using the dashboard, make sure to get yourself familiar with the API Reference (opens in a new tab). 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 credential using OpenID4VCI based on the created template, we will 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 (opens in a new tab) 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": {
        "first_name": "John",
        "last_name": "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.

View your issued credentials

You can retrieve all your 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 (opens in a new tab) in the API reference.

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 (opens in a new tab) and let us know. Happy building!

API Reference Verify Credentials