Create and verify EBSI-compliant W3C Verifiable Credentials in JWT format.

For more details, see VC Framework.

Notes:

• this library implements the VC Data Model 1.1 specification and VC Data Model 2.0 specification.
• this library only supports 2020-12 JSON Schemas.

Installation

Using npm:

npm i --save did-jwt @cef-ebsi/verifiable-credential

Using yarn:

yarn add did-jwt @cef-ebsi/verifiable-credential

Before you begin

info

While the base Verifiable Attestation schema doesn't restrict the type property of credentialSchema and credentialStatus to specific values, please note that the VC library only supports the following values:

• For credentialSchema.type: FullJsonSchemaValidator2021 or JsonSchema
• For credentialStatus.type: StatusList2021Entry (VCDM 1.1 only) or BitstringStatusListEntry

Usage

The library exposes 2 main entry points. Depending on the VCDM version that you want to support (1.1 or 2.0), you will import one or the other:

• "@cef-ebsi/verifiable-credential/vcdm11.js" for VCDM 1.1 credentials
• "@cef-ebsi/verifiable-credential/vcdm20.js" for VCDM 2.0 credentials

The APIs exposed by the 2 entry points are almost identical. The main difference is related to the credentials payload.

VCDM 1.1

Configuration

All the methods described below require a configuration object. The library exports a TypeScript interface that you can use to properly define the configuration object. Here's an example of such a configuration object:

import type { EbsiEnvConfiguration } from "@cef-ebsi/verifiable-credential/vcdm11.js";

const config = {
  // List of trusted hosts
  hosts: ["api-test.ebsi.eu"],

  // Defines the URI scheme
  scheme: "ebsi",

  // Defines the network config
  network: {
    // Network component, as it appears in the URI
    name: "test",

    // Whether the network component is optional or not
    isOptional: false,
  },

  // The list of the supported services (with their version number)
  services: {
    "did-registry": "v5",
    "trusted-issuers-registry": "v5",
    "trusted-policies-registry": "v3",
    "trusted-schemas-registry": "v3",
  },
} as const satisfies EbsiEnvConfiguration;

Creating JWTs

Prerequisites

In order to create a valid JWT, the issuer must either be:

1. a Legal Entity (did:ebsi method). In this case, the issuer must also be registered in the DID Registry.
2. a Natural Person (did:key method).

Creating a Verifiable Credential as a Legal Entity

Create an EbsiIssuer object to sign JWTs:

import type { EbsiIssuer } from "@cef-ebsi/verifiable-credential/vcdm11.js";
import { ES256Signer } from "@cef-ebsi/did-jwt";
import { hexToBytes } from "@noble/curves/utils.js";

const privateKey = hexToBytes("<hex private key>");
const issuer = {
  alg: "ES256",
  did: "did:ebsi:ztTYEydcPQ2SrKoghHqxBfK",
  kid: "did:ebsi:ztTYEydcPQ2SrKoghHqxBfK#BENdjDfatlKj-uQovYJlO_8SjOcVHvi6HrXKLKEB7Po",
  signer: ES256Signer(privateKey),
} satisfies EbsiIssuer;

Specify a payload matching the Schemas["Attestation"] interface. If your credential references an IssuanceCertificate accreditation, you can also import the TypeExtensions interface and make sure the payload extends TypeExtensions["termsOfUse"]["IssuanceCertificate"]:

import {
  createVerifiableCredentialJwt,
  type Schemas,
  type TypeExtensions,
} from "@cef-ebsi/verifiable-credential/vcdm11.js";

const vcPayload = {
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  id: "urn:uuid:003a1dd8-a5d2-42ef-8182-e921c0a9f2cd",
  type: ["VerifiableCredential", "VerifiableAttestation"],
  issuer: "did:ebsi:ztTYEydcPQ2SrKoghHqxBfK",
  issuanceDate: "2026-01-08T15:00:12Z",
  issued: "2026-01-08T15:00:12Z",
  validFrom: "2026-01-08T15:00:12Z",
  validUntil: "2026-02-07T15:00:22Z",
  expirationDate: "2026-02-07T15:00:22Z",
  credentialSubject: {
    id: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r",
  },
  credentialSchema: [
    {
      id: "https://api-test.ebsi.eu/trusted-schemas-registry/v3/schemas/zH74MKkYTbQ6ZfTxufi6A3Aw8giS4piGm8dpgxFmkJjmu",
      type: "FullJsonSchemaValidator2021",
    },
    {
      id: "https://api-test.ebsi.eu/trusted-schemas-registry/v3/schemas/zDidyzBSNZV1jwjauh6CPYJL6cy6XWcHjbeMXQXmTzox8",
      type: "FullJsonSchemaValidator2021",
    },
  ],
  termsOfUse: {
    id: "https://api-test.ebsi.eu/trusted-issuers-registry/v5/issuers/did:ebsi:ztTYEydcPQ2SrKoghHqxBfK/attributes/36420f369546ca099509760c1e42fda78609453248db7082cc2a33478761e3f0",
    type: "IssuanceCertificate",
  },
} satisfies Schemas["Attestation"] &
  TypeExtensions["termsOfUse"]["IssuanceCertificate"];

Specify the options to validate the issuer and credential:

import type { CreateVerifiableCredentialOptions } from "@cef-ebsi/verifiable-credential/vcdm11.js";

const options = {
  /**
   * Custom Axios request headers
   */
  // axiosHeaders?: RawAxiosRequestHeaders;
  /**
   * Time in seconds expanding the validity period of the JWT, both before "nbf" and after "exp". Default : 0 second.
   * Note: the did-jwt library uses a similar `skewTime` parameter with a default value of 5 minutes (300 seconds).
   */
  // clockSkew?: number;
  /**
   * Extra credentialSchema types. By default, the library only supports "FullJsonSchemaValidator2021" and "JsonSchema".
   * The library is not responsible for validating these extra types.
   */
  // extraCredentialSchemaTypes?: string[];
  /**
   * Additional header parameters to add to the JWT header
   */
  // header?: Record<string, unknown>;
  /**
   * Determines whether to validate the accreditations of the VC issuer or not.
   * Validation is active by default.
   * @defaultValue false
   */
  // skipAccreditationsValidation?: boolean;
  /**
   * Determines whether to validate the credential subject or not
   * Validation is active by default.
   */
  // skipCredentialSubjectValidation?: boolean;
  /**
   * Determines whether to validate the credential status or not
   * Validation is active by default.
   * @defaultValue false
   */
  // skipStatusValidation?: boolean;
  /**
   * Determines whether to validate the Verifiable Credential payload or not.
   * Validation is active by default.
   *
   * Note: even when skipValidation is set to true, the payload must be a valid
   * EBSI Verifiable Attestation.
   * @defaultValue false
   */
  // skipValidation?: boolean;
  /**
   * Credential subject. This parameter is mandatory if the payload's `credentialSubject` is an array.
   * It must correspond to one of the IDs in the payload's `credentialSubject` array.
   */
  // sub?: string;
  /**
   * Axios requests timeout (in milliseconds). Default: 15 seconds
   */
  // timeout?: number;
  /**
   * Unix timestamp. Optional comparison date. Default: current date and time.
   * For the JWT to be valid, `nbf` ≤ `validAt` ≤ `exp`.
   */
  // validAt?: number;
} satisfies CreateVerifiableCredentialOptions;

Create a JWT by signing it with the previously configured issuer using the createVerifiableCredentialJwt function:

const vcJwt = await createVerifiableCredentialJwt(
  vcPayload,
  issuer,
  config,
  options,
);
console.log(vcJwt);
// eyJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDplYnNpOnp0VFlFeWRjUFEyU3JLb2doSHF4QmZLI0JFTmRqRGZhdGxLai11UW92WUpsT184U2pPY1ZIdmk2SHJYS0xLRUI3UG8iLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3Njc4ODQ0MTIsImp0aSI6InVybjp1dWlkOjAwM2ExZGQ4LWE1ZDItNDJlZi04MTgyLWU5MjFjMGE5ZjJjZCIsInN1YiI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic0VZdmRyanhNalE0dHBuamU5QkRCVHp1TkRQM2tubjZxTFpFcnpkNGJKNWdvMkNDaG9QamQ1R0FIM3pwRkpQNWZ1d1NrNjZVNVBxNkVoRjRuS25IekRuem5FUDhmWDk5blpHZ3diQWgxbzdHajFYNTJUZGhmN1U0S1RrNjZ4c0E1ciIsImlzcyI6ImRpZDplYnNpOnp0VFlFeWRjUFEyU3JLb2doSHF4QmZLIiwibmJmIjoxNzY3ODg0NDEyLCJleHAiOjE3NzA0NzY0MjIsInZjIjp7IkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIl0sImlkIjoidXJuOnV1aWQ6MDAzYTFkZDgtYTVkMi00MmVmLTgxODItZTkyMWMwYTlmMmNkIiwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVudGlhbCIsIlZlcmlmaWFibGVBdHRlc3RhdGlvbiJdLCJpc3N1ZXIiOiJkaWQ6ZWJzaTp6dFRZRXlkY1BRMlNyS29naEhxeEJmSyIsImlzc3VhbmNlRGF0ZSI6IjIwMjYtMDEtMDhUMTU6MDA6MTJaIiwiaXNzdWVkIjoiMjAyNi0wMS0wOFQxNTowMDoxMloiLCJ2YWxpZEZyb20iOiIyMDI2LTAxLTA4VDE1OjAwOjEyWiIsInZhbGlkVW50aWwiOiIyMDI2LTAyLTA3VDE1OjAwOjIyWiIsImV4cGlyYXRpb25EYXRlIjoiMjAyNi0wMi0wN1QxNTowMDoyMloiLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic0VZdmRyanhNalE0dHBuamU5QkRCVHp1TkRQM2tubjZxTFpFcnpkNGJKNWdvMkNDaG9QamQ1R0FIM3pwRkpQNWZ1d1NrNjZVNVBxNkVoRjRuS25IekRuem5FUDhmWDk5blpHZ3diQWgxbzdHajFYNTJUZGhmN1U0S1RrNjZ4c0E1ciJ9LCJjcmVkZW50aWFsU2NoZW1hIjpbeyJpZCI6Imh0dHBzOi8vYXBpLXRlc3QuZWJzaS5ldS90cnVzdGVkLXNjaGVtYXMtcmVnaXN0cnkvdjMvc2NoZW1hcy96SDc0TUtrWVRiUTZaZlR4dWZpNkEzQXc4Z2lTNHBpR204ZHBneEZta0pqbXUiLCJ0eXBlIjoiRnVsbEpzb25TY2hlbWFWYWxpZGF0b3IyMDIxIn0seyJpZCI6Imh0dHBzOi8vYXBpLXRlc3QuZWJzaS5ldS90cnVzdGVkLXNjaGVtYXMtcmVnaXN0cnkvdjMvc2NoZW1hcy96RGlkeXpCU05aVjFqd2phdWg2Q1BZSkw2Y3k2WFdjSGpiZU1YUVhtVHpveDgiLCJ0eXBlIjoiRnVsbEpzb25TY2hlbWFWYWxpZGF0b3IyMDIxIn1dLCJ0ZXJtc09mVXNlIjp7ImlkIjoiaHR0cHM6Ly9hcGktdGVzdC5lYnNpLmV1L3RydXN0ZWQtaXNzdWVycy1yZWdpc3RyeS92NS9pc3N1ZXJzL2RpZDplYnNpOnp0VFlFeWRjUFEyU3JLb2doSHF4QmZLL2F0dHJpYnV0ZXMvMzY0MjBmMzY5NTQ2Y2EwOTk1MDk3NjBjMWU0MmZkYTc4NjA5NDUzMjQ4ZGI3MDgyY2MyYTMzNDc4NzYxZTNmMCIsInR5cGUiOiJJc3N1YW5jZUNlcnRpZmljYXRlIn19fQ.BnicLTT_wL7bmSgxDRDgUgd3rp0L9Il7pLReGwQdNauMIGktbw_fk3e576TDLntOHTKdTNV_mmriLyS0vJlY8A

Creating a Verifiable Credential as a Natural Person

Create an EbsiIssuer object to sign JWTs:

import type { EbsiIssuer } from "@cef-ebsi/verifiable-credential/vcdm11.js";
import { ES256Signer } from "@cef-ebsi/did-jwt";
import { hexToBytes } from "@noble/curves/utils.js";

const privateKey = hexToBytes("<hex private key>");
const x = "";
const issuer = {
  alg: "ES256",
  did: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsDbVZXdb3jzCagESyY4EE2x7Yjx3gNwctoEuRCKKDrdNP3HPFtG8RTvBiYStT5ghBHhHizH2Dy6xQtW3Pd2SecizL9b2jzDCMr7Ka5cRAWZFwvqwAtwTT7xet769y9ERh6",
  kid: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsDbVZXdb3jzCagESyY4EE2x7Yjx3gNwctoEuRCKKDrdNP3HPFtG8RTvBiYStT5ghBHhHizH2Dy6xQtW3Pd2SecizL9b2jzDCMr7Ka5cRAWZFwvqwAtwTT7xet769y9ERh6#z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsDbVZXdb3jzCagESyY4EE2x7Yjx3gNwctoEuRCKKDrdNP3HPFtG8RTvBiYStT5ghBHhHizH2Dy6xQtW3Pd2SecizL9b2jzDCMr7Ka5cRAWZFwvqwAtwTT7xet769y9ERh6",
  signer: ES256Signer(privateKey),
} satisfies EbsiIssuer;

Specify a payload matching the Schemas["Attestation"] interface:

import {
  createVerifiableCredentialJwt,
  type Schemas,
} from "@cef-ebsi/verifiable-credential/vcdm11.js";

const vcPayload = {
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  id: "urn:uuid:003a1dd8-a5d2-42ef-8182-e921c0a9f2cd",
  type: ["VerifiableCredential", "VerifiableAttestation"],
  issuer:
    "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsDbVZXdb3jzCagESyY4EE2x7Yjx3gNwctoEuRCKKDrdNP3HPFtG8RTvBiYStT5ghBHhHizH2Dy6xQtW3Pd2SecizL9b2jzDCMr7Ka5cRAWZFwvqwAtwTT7xet769y9ERh6",
  issuanceDate: "2026-01-08T15:00:12Z",
  issued: "2026-01-08T15:00:12Z",
  validFrom: "2026-01-08T15:00:12Z",
  validUntil: "2026-02-07T15:00:22Z",
  expirationDate: "2026-02-07T15:00:22Z",
  credentialSubject: {
    id: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r",
  },
  credentialSchema: {
    id: "https://api-test.ebsi.eu/trusted-schemas-registry/v3/schemas/zH74MKkYTbQ6ZfTxufi6A3Aw8giS4piGm8dpgxFmkJjmu",
    type: "FullJsonSchemaValidator2021",
  },
} satisfies Schemas["Attestation"];

Specify the options to validate the issuer and credential:

import type { CreateVerifiableCredentialOptions } from "@cef-ebsi/verifiable-credential/vcdm11.js";

const options = {
  timeout: 15_000,
} as const satisfies CreateVerifiableCredentialOptions;

Create a JWT by signing it with the previously configured issuer using the createVerifiableCredentialJwt function:

const vcJwt = await createVerifiableCredentialJwt(
  vcPayload,
  issuer,
  config,
  options,
);
console.log(vcJwt);
// eyJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic0RiVlpYZGIzanpDYWdFU3lZNEVFMng3WWp4M2dOd2N0b0V1UkNLS0RyZE5QM0hQRnRHOFJUdkJpWVN0VDVnaEJIaEhpekgyRHk2eFF0VzNQZDJTZWNpekw5YjJqekRDTXI3S2E1Y1JBV1pGd3Zxd0F0d1RUN3hldDc2OXk5RVJoNiN6MmRtekQ4MWNnUHg4VmtpN0pidXVNbUZZcldQZ1lveXR5a1VaM2V5cWh0MWo5S2JzRGJWWlhkYjNqekNhZ0VTeVk0RUUyeDdZangzZ053Y3RvRXVSQ0tLRHJkTlAzSFBGdEc4UlR2QmlZU3RUNWdoQkhoSGl6SDJEeTZ4UXRXM1BkMlNlY2l6TDliMmp6RENNcjdLYTVjUkFXWkZ3dnF3QXR3VFQ3eGV0NzY5eTlFUmg2IiwidHlwIjoiSldUIn0.eyJpYXQiOjE3Njc4ODQ0MTIsImp0aSI6InVybjp1dWlkOjAwM2ExZGQ4LWE1ZDItNDJlZi04MTgyLWU5MjFjMGE5ZjJjZCIsInN1YiI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic0VZdmRyanhNalE0dHBuamU5QkRCVHp1TkRQM2tubjZxTFpFcnpkNGJKNWdvMkNDaG9QamQ1R0FIM3pwRkpQNWZ1d1NrNjZVNVBxNkVoRjRuS25IekRuem5FUDhmWDk5blpHZ3diQWgxbzdHajFYNTJUZGhmN1U0S1RrNjZ4c0E1ciIsImlzcyI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic0RiVlpYZGIzanpDYWdFU3lZNEVFMng3WWp4M2dOd2N0b0V1UkNLS0RyZE5QM0hQRnRHOFJUdkJpWVN0VDVnaEJIaEhpekgyRHk2eFF0VzNQZDJTZWNpekw5YjJqekRDTXI3S2E1Y1JBV1pGd3Zxd0F0d1RUN3hldDc2OXk5RVJoNiIsIm5iZiI6MTc2Nzg4NDQxMiwiZXhwIjoxNzcwNDc2NDIyLCJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSJdLCJpZCI6InVybjp1dWlkOjAwM2ExZGQ4LWE1ZDItNDJlZi04MTgyLWU5MjFjMGE5ZjJjZCIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJWZXJpZmlhYmxlQXR0ZXN0YXRpb24iXSwiaXNzdWVyIjoiZGlkOmtleTp6MmRtekQ4MWNnUHg4VmtpN0pidXVNbUZZcldQZ1lveXR5a1VaM2V5cWh0MWo5S2JzRGJWWlhkYjNqekNhZ0VTeVk0RUUyeDdZangzZ053Y3RvRXVSQ0tLRHJkTlAzSFBGdEc4UlR2QmlZU3RUNWdoQkhoSGl6SDJEeTZ4UXRXM1BkMlNlY2l6TDliMmp6RENNcjdLYTVjUkFXWkZ3dnF3QXR3VFQ3eGV0NzY5eTlFUmg2IiwiaXNzdWFuY2VEYXRlIjoiMjAyNi0wMS0wOFQxNTowMDoxMloiLCJpc3N1ZWQiOiIyMDI2LTAxLTA4VDE1OjAwOjEyWiIsInZhbGlkRnJvbSI6IjIwMjYtMDEtMDhUMTU6MDA6MTJaIiwidmFsaWRVbnRpbCI6IjIwMjYtMDItMDdUMTU6MDA6MjJaIiwiZXhwaXJhdGlvbkRhdGUiOiIyMDI2LTAyLTA3VDE1OjAwOjIyWiIsImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiZGlkOmtleTp6MmRtekQ4MWNnUHg4VmtpN0pidXVNbUZZcldQZ1lveXR5a1VaM2V5cWh0MWo5S2JzRVl2ZHJqeE1qUTR0cG5qZTlCREJUenVORFAza25uNnFMWkVyemQ0Yko1Z28yQ0Nob1BqZDVHQUgzenBGSlA1ZnV3U2s2NlU1UHE2RWhGNG5Lbkh6RG56bkVQOGZYOTluWkdnd2JBaDFvN0dqMVg1MlRkaGY3VTRLVGs2NnhzQTVyIn0sImNyZWRlbnRpYWxTY2hlbWEiOnsiaWQiOiJodHRwczovL2FwaS10ZXN0LmVic2kuZXUvdHJ1c3RlZC1zY2hlbWFzLXJlZ2lzdHJ5L3YzL3NjaGVtYXMvekg3NE1La1lUYlE2WmZUeHVmaTZBM0F3OGdpUzRwaUdtOGRwZ3hGbWtKam11IiwidHlwZSI6IkZ1bGxKc29uU2NoZW1hVmFsaWRhdG9yMjAyMSJ9fX0.7BQxMPaiOD67fKWRXk2eQ_EpF5H5CSdeL0lfmQQUsA8sOOJwLtcx_3M_BC_XA7To4fXPOFS6hlt2tU-hRS3qcA

Verifying JWTs

Prerequisites

Verify a VC JWT using the verifyCredentialJwt function:

import {
  verifyCredentialJwt,
  type VerifyCredentialOptions,
} from "@cef-ebsi/verifiable-credential/vcdm11.js";

const vcJwt =
  "eyJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDplYnNpOnp0VFlFeWRjUFEyU3JLb2doSHF4QmZLI0JFTmRqRGZhdGxLai11UW92WUpsT184U2pPY1ZIdmk2SHJYS0xLRUI3UG8iLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3Njc4ODQ0MTIsImp0aSI6InVybjp1dWlkOjAwM2ExZGQ4LWE1ZDItNDJlZi04MTgyLWU5MjFjMGE5ZjJjZCIsInN1YiI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic0VZdmRyanhNalE0dHBuamU5QkRCVHp1TkRQM2tubjZxTFpFcnpkNGJKNWdvMkNDaG9QamQ1R0FIM3pwRkpQNWZ1d1NrNjZVNVBxNkVoRjRuS25IekRuem5FUDhmWDk5blpHZ3diQWgxbzdHajFYNTJUZGhmN1U0S1RrNjZ4c0E1ciIsImlzcyI6ImRpZDplYnNpOnp0VFlFeWRjUFEyU3JLb2doSHF4QmZLIiwibmJmIjoxNzY3ODg0NDEyLCJleHAiOjE3NzA0NzY0MjIsInZjIjp7IkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIl0sImlkIjoidXJuOnV1aWQ6MDAzYTFkZDgtYTVkMi00MmVmLTgxODItZTkyMWMwYTlmMmNkIiwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVudGlhbCIsIlZlcmlmaWFibGVBdHRlc3RhdGlvbiJdLCJpc3N1ZXIiOiJkaWQ6ZWJzaTp6dFRZRXlkY1BRMlNyS29naEhxeEJmSyIsImlzc3VhbmNlRGF0ZSI6IjIwMjYtMDEtMDhUMTU6MDA6MTJaIiwiaXNzdWVkIjoiMjAyNi0wMS0wOFQxNTowMDoxMloiLCJ2YWxpZEZyb20iOiIyMDI2LTAxLTA4VDE1OjAwOjEyWiIsInZhbGlkVW50aWwiOiIyMDI2LTAyLTA3VDE1OjAwOjIyWiIsImV4cGlyYXRpb25EYXRlIjoiMjAyNi0wMi0wN1QxNTowMDoyMloiLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic0VZdmRyanhNalE0dHBuamU5QkRCVHp1TkRQM2tubjZxTFpFcnpkNGJKNWdvMkNDaG9QamQ1R0FIM3pwRkpQNWZ1d1NrNjZVNVBxNkVoRjRuS25IekRuem5FUDhmWDk5blpHZ3diQWgxbzdHajFYNTJUZGhmN1U0S1RrNjZ4c0E1ciJ9LCJjcmVkZW50aWFsU2NoZW1hIjpbeyJpZCI6Imh0dHBzOi8vYXBpLXRlc3QuZWJzaS5ldS90cnVzdGVkLXNjaGVtYXMtcmVnaXN0cnkvdjMvc2NoZW1hcy96SDc0TUtrWVRiUTZaZlR4dWZpNkEzQXc4Z2lTNHBpR204ZHBneEZta0pqbXUiLCJ0eXBlIjoiRnVsbEpzb25TY2hlbWFWYWxpZGF0b3IyMDIxIn0seyJpZCI6Imh0dHBzOi8vYXBpLXRlc3QuZWJzaS5ldS90cnVzdGVkLXNjaGVtYXMtcmVnaXN0cnkvdjMvc2NoZW1hcy96RGlkeXpCU05aVjFqd2phdWg2Q1BZSkw2Y3k2WFdjSGpiZU1YUVhtVHpveDgiLCJ0eXBlIjoiRnVsbEpzb25TY2hlbWFWYWxpZGF0b3IyMDIxIn1dLCJ0ZXJtc09mVXNlIjp7ImlkIjoiaHR0cHM6Ly9hcGktdGVzdC5lYnNpLmV1L3RydXN0ZWQtaXNzdWVycy1yZWdpc3RyeS92NS9pc3N1ZXJzL2RpZDplYnNpOnp0VFlFeWRjUFEyU3JLb2doSHF4QmZLL2F0dHJpYnV0ZXMvMzY0MjBmMzY5NTQ2Y2EwOTk1MDk3NjBjMWU0MmZkYTc4NjA5NDUzMjQ4ZGI3MDgyY2MyYTMzNDc4NzYxZTNmMCIsInR5cGUiOiJJc3N1YW5jZUNlcnRpZmljYXRlIn19fQ.BnicLTT_wL7bmSgxDRDgUgd3rp0L9Il7pLReGwQdNauMIGktbw_fk3e576TDLntOHTKdTNV_mmriLyS0vJlY8A";

const options = {
  /**
   * Custom Axios request headers
   */
  // axiosHeaders?: RawAxiosRequestHeaders;
  /**
   * Time in seconds expanding the validity period of the JWT, both before "nbf" and after "exp". Default : 0 second.
   * Note: the did-jwt library uses a similar `skewTime` parameter with a default value of 5 minutes (300 seconds).
   */
  // clockSkew?: number;
  /**
   * Extra credentialSchema types. By default, the library only supports "FullJsonSchemaValidator2021" and "JsonSchema".
   * The library is not responsible for validating these extra types.
   */
  // extraCredentialSchemaTypes?: string[];
  /**
   * Determines whether to validate the accreditations of the VC issuer or not.
   * Validation is active by default.
   * @defaultValue false
   */
  // skipAccreditationsValidation?: boolean;
  /**
   * Determines whether to validate the credential subject or not
   * Validation is active by default.
   */
  // skipCredentialSubjectValidation?: boolean;
  /**
   * Determines whether to validate the credential status or not.
   * Validation is active by default.
   * @defaultValue false
   */
  // skipStatusValidation?: boolean;
  /**
   * Axios requests timeout (in milliseconds). Default: 15 seconds
   */
  // timeout?: number;
  /**
   * Unix timestamp. Optional comparison date. Default: current date and time.
   * For the JWT to be valid, `nbf` ≤ `validAt` ≤ `exp`.
   */
  // validAt?: number;
  /**
   * Determines whether or not to validate the issuer's accreditations when `termsOfUse` is missing.
   * @defaultValue false
   */
  // validateAccreditationWithoutTermsOfUse?: boolean;
} satisfies VerifyCredentialOptions;

const verifiedVc = await verifyCredentialJwt(vcJwt, config, options);

console.log(JSON.stringify(verifiedVc, undefined, 2));
/*
 {
  "@context": [
    "https://www.w3.org/2018/credentials/v1"
  ],
  "id": "urn:uuid:003a1dd8-a5d2-42ef-8182-e921c0a9f2cd",
  "type": [
    "VerifiableCredential",
    "VerifiableAttestation"
  ],
  "issuer": "did:ebsi:ztTYEydcPQ2SrKoghHqxBfK",
  "issuanceDate": "2026-01-08T15:00:12Z",
  "issued": "2026-01-08T15:00:12Z",
  "validFrom": "2026-01-08T15:00:12Z",
  "validUntil": "2026-02-07T15:00:22Z",
  "expirationDate": "2026-02-07T15:00:22Z",
  "credentialSubject": {
    "id": "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r"
  },
  "credentialSchema": [
    {
      "id": "https://api-test.ebsi.eu/trusted-schemas-registry/v3/schemas/zH74MKkYTbQ6ZfTxufi6A3Aw8giS4piGm8dpgxFmkJjmu",
      "type": "FullJsonSchemaValidator2021"
    },
    {
      "id": "https://api-test.ebsi.eu/trusted-schemas-registry/v3/schemas/zDidyzBSNZV1jwjauh6CPYJL6cy6XWcHjbeMXQXmTzox8",
      "type": "FullJsonSchemaValidator2021"
    }
  ],
  "termsOfUse": {
    "id": "https://api-test.ebsi.eu/trusted-issuers-registry/v5/issuers/did:ebsi:ztTYEydcPQ2SrKoghHqxBfK/attributes/36420f369546ca099509760c1e42fda78609453248db7082cc2a33478761e3f0",
    "type": "IssuanceCertificate"
  }
}
*/

Verification process

The verification of the credentials is performed using the following process:

1. Header

• The alg property must be ES256, ES256K, or EdDSA.
• The kid property must contain the DID of the issuer and the fragment identifier allowing to know which verification method to use.

2. Basic properties in the payload

• The payload must contain a vc property containing an EBSI Verifiable Attestation.
• The iss property must match the VC issuer vc.issuer.
• The sub property must match the VC credential subject vc.credentialSubject.id.
• The jti property must match the VC ID vc.id.
• The iat property must refer to the date in VC issued vc.issued.
• The nbf property must refer to the date in VC valid from vc.validFrom.
• The exp property mush refer to date in VC expiration date vc.expirationDate (for VCDM 1.1) or vc.validUntil (for VCDM 2.0) in the case it is defined.

3. Signature

• The signature must be validated against the verification method from the DID document corresponding to the VC JWT kid header.

4. Extra validations to the VC payload

• Validation of @context.
• Validation of type.
• Validation of dates.

5. Issuer in Trusted Issuers Registry

If the issuer is a Legal Entity:

• The issuer must be registered in the Trusted Issuers Registry.

Additionally, if the VC is an attestation with accreditation:

• The VC must contain a termsOfUse property pointing to the accreditations of the issuer.
• The issuer must be accredited to issue the types present in the credential.

6. Credential subject

• The credential subject must be a valid DID, using either the did:ebsi v1 method (Legal Entity) or the did:key method (Natural Person).

7. Credential schema

• The VC credential schema(s) must link to valid EBSI credential schemas, registered in the Trusted Schemas Registry.
• The credential payload is validated against the aforementioned JSON Schemas.

VCDM 2.0

Configuration

All the methods described below require a configuration object. The library exports a TypeScript interface that you can use to properly define the configuration object. Here's an example of such a configuration object:

import type { EbsiEnvConfiguration } from "@cef-ebsi/verifiable-credential/vcdm20.js";

const config = {
  // List of trusted hosts
  hosts: ["api-pilot.ebsi.eu"],

  // Defines the URI scheme
  scheme: "ebsi",

  // Defines the network config
  network: {
    // Network component, as it appears in the URI
    name: "pilot",

    // Whether the network component is optional or not
    isOptional: false,
  },

  // The list of the supported services (with their version number)
  services: {
    "did-registry": "v5",
    "trusted-issuers-registry": "v5",
    "trusted-policies-registry": "v3",
    "trusted-schemas-registry": "v3",
  },
} as const satisfies EbsiEnvConfiguration;

Creating JWTs

Prerequisites

In order to create a valid JWT, the issuer must either be:

1. a Legal Entity (did:ebsi method). In this case, the issuer must also be registered in the DID Registry.
2. a Natural Person (did:key method).

Creating a Verifiable Credential as a Legal Entity

Create an EbsiIssuer object to sign JWTs:

import type { EbsiIssuer } from "@cef-ebsi/verifiable-credential/vcdm11.js";
import { ES256Signer } from "@cef-ebsi/did-jwt";
import { hexToBytes } from "@noble/curves/utils.js";

const privateKey = hexToBytes("<hex private key>");
const issuer = {
  alg: "ES256",
  did: "did:ebsi:ztTYEydcPQ2SrKoghHqxBfK",
  kid: "did:ebsi:ztTYEydcPQ2SrKoghHqxBfK#BENdjDfatlKj-uQovYJlO_8SjOcVHvi6HrXKLKEB7Po",
  signer: ES256Signer(privateKey),
} satisfies EbsiIssuer;

Specify a payload matching the Schemas["Attestation"] interface. If your credential references an AttestationPolicy accreditation, you can also import the TypeExtensions interface and make sure the payload extends TypeExtensions["termsOfUse"]["AttestationPolicy"]:

import {
  createVerifiableCredentialJwt,
  type Schemas,
  type TypeExtensions,
} from "@cef-ebsi/verifiable-credential/vcdm20.js";

const vcPayload = {
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  id: "urn:uuid:003a1dd8-a5d2-42ef-8182-e921c0a9f2cd",
  type: ["VerifiableCredential", "VerifiableAttestation"],
  issuer: "did:ebsi:ztTYEydcPQ2SrKoghHqxBfK",
  validFrom: "2026-01-08T15:17:51Z",
  validUntil: "2026-02-07T15:18:01Z",
  credentialSubject: {
    id: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r",
  },
  credentialSchema: [
    {
      id: "https://api-test.ebsi.eu/trusted-schemas-registry/v3/schemas/zB5yLy7GXdZs1iaJ7wN2K5mhwZDTxjECM2fELYE73mu3E",
      type: "FullJsonSchemaValidator2021",
    },
    {
      id: "https://api-test.ebsi.eu/trusted-schemas-registry/v3/schemas/z6LZcdHUQ91uirxiuqKrYFzzc9X4uB3bUYXDEkwWeyZmr",
      type: "FullJsonSchemaValidator2021",
    },
  ],
  termsOfUse: {
    parentAccreditation:
      "https://api-test.ebsi.eu/trusted-issuers-registry/v5/issuers/did:ebsi:ztTYEydcPQ2SrKoghHqxBfK/attributes/5627692d742d51e8c73e7a82b89c4d2200e3b8c78423aecb8673153ba74ed8ba",
    rootAuthorisation:
      "https://api-test.ebsi.eu/trusted-issuers-registry/v5/issuers/did:ebsi:ztTYEydcPQ2SrKoghHqxBfK/attributes/5627692d742d51e8c73e7a82b89c4d2200e3b8c78423aecb8673153ba74ed8ba",
    type: "AttestationPolicy",
  },
} satisfies Schemas["Attestation"] &
  TypeExtensions["termsOfUse"]["AttestationPolicy"];

Specify the options to validate the issuer and credential:

import type { CreateVerifiableCredentialOptions } from "@cef-ebsi/verifiable-credential/vcdm20.js";

const options = {
  /**
   * Custom Axios request headers
   */
  // axiosHeaders?: RawAxiosRequestHeaders;
  /**
   * Time in seconds expanding the validity period of the JWT, both before "nbf" and after "exp". Default : 0 second.
   * Note: the did-jwt library uses a similar `skewTime` parameter with a default value of 5 minutes (300 seconds).
   */
  // clockSkew?: number;
  /**
   * Extra credentialSchema types. By default, the library only supports "FullJsonSchemaValidator2021" and "JsonSchema".
   * The library is not responsible for validating these extra types.
   */
  // extraCredentialSchemaTypes?: string[];
  /**
   * Additional header parameters to add to the JWT header
   */
  // header?: Partial<VcJwtHeader>;
  /**
   * Additional JWT claims to add to the VC JWT payload
   */
  // payload?: Partial<VcJwtClaims>;
  /**
   * Determines whether to validate the accreditations of the VC issuer or not.
   * Validation is active by default.
   * @defaultValue false
   */
  // skipAccreditationsValidation?: boolean;
  /**
   * Determines whether to validate the credential subject or not
   * Validation is active by default.
   */
  // skipCredentialSubjectValidation?: boolean;
  /**
   * Determines whether to validate the credential status or not
   * Validation is active by default.
   * @defaultValue false
   */
  // skipStatusValidation?: boolean;
  /**
   * Determines whether to validate the Verifiable Credential payload or not.
   * Validation is active by default.
   *
   * Note: even when skipValidation is set to true, the payload must be a valid
   * EBSI Verifiable Attestation.
   * @defaultValue false
   */
  // skipValidation?: boolean;
  /**
   * Axios requests timeout (in milliseconds). Default: 15 seconds
   */
  // timeout?: number;
  /**
   * Unix timestamp. Optional comparison date. Default: current date and time.
   * For the credential to be valid, `validFrom` ≤ `validAt` ≤ `validUntil`.
   */
  // validAt?: number;
} satisfies CreateVerifiableCredentialOptions;

Create a JWT by signing it with the previously configured issuer using the createVerifiableCredentialJwt function:

const vcJwt = await createVerifiableCredentialJwt(
  vcPayload,
  issuer,
  config,
  options,
);
console.log(vcJwt);
// eyJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDplYnNpOnp0VFlFeWRjUFEyU3JLb2doSHF4QmZLI0JFTmRqRGZhdGxLai11UW92WUpsT184U2pPY1ZIdmk2SHJYS0xLRUI3UG8iLCJ0eXAiOiJ2Yytqd3QifQ.eyJpYXQiOjE3Njc4ODU0ODEsIkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy9ucy9jcmVkZW50aWFscy92MiJdLCJpZCI6InVybjp1dWlkOjAwM2ExZGQ4LWE1ZDItNDJlZi04MTgyLWU5MjFjMGE5ZjJjZCIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJWZXJpZmlhYmxlQXR0ZXN0YXRpb24iXSwiaXNzdWVyIjoiZGlkOmVic2k6enRUWUV5ZGNQUTJTcktvZ2hIcXhCZksiLCJ2YWxpZEZyb20iOiIyMDI2LTAxLTA4VDE1OjE3OjUxWiIsInZhbGlkVW50aWwiOiIyMDI2LTAyLTA3VDE1OjE4OjAxWiIsImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiZGlkOmtleTp6MmRtekQ4MWNnUHg4VmtpN0pidXVNbUZZcldQZ1lveXR5a1VaM2V5cWh0MWo5S2JzRVl2ZHJqeE1qUTR0cG5qZTlCREJUenVORFAza25uNnFMWkVyemQ0Yko1Z28yQ0Nob1BqZDVHQUgzenBGSlA1ZnV3U2s2NlU1UHE2RWhGNG5Lbkh6RG56bkVQOGZYOTluWkdnd2JBaDFvN0dqMVg1MlRkaGY3VTRLVGs2NnhzQTVyIn0sImNyZWRlbnRpYWxTY2hlbWEiOlt7ImlkIjoiaHR0cHM6Ly9hcGktdGVzdC5lYnNpLmV1L3RydXN0ZWQtc2NoZW1hcy1yZWdpc3RyeS92My9zY2hlbWFzL3pCNXlMeTdHWGRaczFpYUo3d04ySzVtaHdaRFR4akVDTTJmRUxZRTczbXUzRSIsInR5cGUiOiJGdWxsSnNvblNjaGVtYVZhbGlkYXRvcjIwMjEifSx7ImlkIjoiaHR0cHM6Ly9hcGktdGVzdC5lYnNpLmV1L3RydXN0ZWQtc2NoZW1hcy1yZWdpc3RyeS92My9zY2hlbWFzL3o2TFpjZEhVUTkxdWlyeGl1cUtyWUZ6emM5WDR1QjNiVVlYREVrd1dleVptciIsInR5cGUiOiJGdWxsSnNvblNjaGVtYVZhbGlkYXRvcjIwMjEifV0sInRlcm1zT2ZVc2UiOnsicGFyZW50QWNjcmVkaXRhdGlvbiI6Imh0dHBzOi8vYXBpLXRlc3QuZWJzaS5ldS90cnVzdGVkLWlzc3VlcnMtcmVnaXN0cnkvdjUvaXNzdWVycy9kaWQ6ZWJzaTp6dFRZRXlkY1BRMlNyS29naEhxeEJmSy9hdHRyaWJ1dGVzLzU2Mjc2OTJkNzQyZDUxZThjNzNlN2E4MmI4OWM0ZDIyMDBlM2I4Yzc4NDIzYWVjYjg2NzMxNTNiYTc0ZWQ4YmEiLCJyb290QXV0aG9yaXNhdGlvbiI6Imh0dHBzOi8vYXBpLXRlc3QuZWJzaS5ldS90cnVzdGVkLWlzc3VlcnMtcmVnaXN0cnkvdjUvaXNzdWVycy9kaWQ6ZWJzaTp6dFRZRXlkY1BRMlNyS29naEhxeEJmSy9hdHRyaWJ1dGVzLzU2Mjc2OTJkNzQyZDUxZThjNzNlN2E4MmI4OWM0ZDIyMDBlM2I4Yzc4NDIzYWVjYjg2NzMxNTNiYTc0ZWQ4YmEiLCJ0eXBlIjoiQXR0ZXN0YXRpb25Qb2xpY3kifX0.YQbWkxheFKk7sK-H0OAePd6ismw_kJ3ITOBDa5W4u2eSWN1e65PylcEqLmD1Fw18ujv8hxIyTTDhf4pxOzAlVQ

Creating a Verifiable Credential as a Natural Person

Create an EbsiIssuer object to sign JWTs:

import type { EbsiIssuer } from "@cef-ebsi/verifiable-credential/vcdm20.js";
import { ES256Signer } from "@cef-ebsi/did-jwt";
import { hexToBytes } from "@noble/curves/utils.js";

const privateKey = hexToBytes("<hex private key>");
const issuer = {
  alg: "ES256",
  did: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsDbVZXdb3jzCagESyY4EE2x7Yjx3gNwctoEuRCKKDrdNP3HPFtG8RTvBiYStT5ghBHhHizH2Dy6xQtW3Pd2SecizL9b2jzDCMr7Ka5cRAWZFwvqwAtwTT7xet769y9ERh6",
  kid: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsDbVZXdb3jzCagESyY4EE2x7Yjx3gNwctoEuRCKKDrdNP3HPFtG8RTvBiYStT5ghBHhHizH2Dy6xQtW3Pd2SecizL9b2jzDCMr7Ka5cRAWZFwvqwAtwTT7xet769y9ERh6#z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsDbVZXdb3jzCagESyY4EE2x7Yjx3gNwctoEuRCKKDrdNP3HPFtG8RTvBiYStT5ghBHhHizH2Dy6xQtW3Pd2SecizL9b2jzDCMr7Ka5cRAWZFwvqwAtwTT7xet769y9ERh6",
  signer: ES256Signer(privateKey),
} satisfies EbsiIssuer;

Specify a payload matching the Schemas["Attestation"] interface:

import {
  createVerifiableCredentialJwt,
  type Schemas,
} from "@cef-ebsi/verifiable-credential/vcdm20.js";

const vcPayload = {
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  id: "urn:uuid:003a1dd8-a5d2-42ef-8182-e921c0a9f2cd",
  type: ["VerifiableCredential", "VerifiableAttestation"],
  issuer:
    "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsDbVZXdb3jzCagESyY4EE2x7Yjx3gNwctoEuRCKKDrdNP3HPFtG8RTvBiYStT5ghBHhHizH2Dy6xQtW3Pd2SecizL9b2jzDCMr7Ka5cRAWZFwvqwAtwTT7xet769y9ERh6",
  validFrom: "2026-01-08T15:17:51Z",
  validUntil: "2026-02-07T15:18:01Z",
  credentialSubject: {
    id: "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r",
  },
  credentialSchema: {
    id: "https://api-test.ebsi.eu/trusted-schemas-registry/v3/schemas/zB5yLy7GXdZs1iaJ7wN2K5mhwZDTxjECM2fELYE73mu3E",
    type: "FullJsonSchemaValidator2021",
  },
} satisfies Schemas["Attestation"];

Specify the options to validate the issuer and credential:

import type { CreateVerifiableCredentialOptions } from "@cef-ebsi/verifiable-credential/vcdm20.js";

const options = {
  timeout: 15_000,
} as const satisfies CreateVerifiableCredentialOptions;

Create a JWT by signing it with the previously configured issuer using the createVerifiableCredentialJwt function:

const vcJwt = await createVerifiableCredentialJwt(
  vcPayload,
  issuer,
  config,
  options,
);
console.log(vcJwt);
// eyJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic0RiVlpYZGIzanpDYWdFU3lZNEVFMng3WWp4M2dOd2N0b0V1UkNLS0RyZE5QM0hQRnRHOFJUdkJpWVN0VDVnaEJIaEhpekgyRHk2eFF0VzNQZDJTZWNpekw5YjJqekRDTXI3S2E1Y1JBV1pGd3Zxd0F0d1RUN3hldDc2OXk5RVJoNiN6MmRtekQ4MWNnUHg4VmtpN0pidXVNbUZZcldQZ1lveXR5a1VaM2V5cWh0MWo5S2JzRGJWWlhkYjNqekNhZ0VTeVk0RUUyeDdZangzZ053Y3RvRXVSQ0tLRHJkTlAzSFBGdEc4UlR2QmlZU3RUNWdoQkhoSGl6SDJEeTZ4UXRXM1BkMlNlY2l6TDliMmp6RENNcjdLYTVjUkFXWkZ3dnF3QXR3VFQ3eGV0NzY5eTlFUmg2IiwidHlwIjoidmMrand0In0.eyJpYXQiOjE3Njc4ODU0ODEsIkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy9ucy9jcmVkZW50aWFscy92MiJdLCJpZCI6InVybjp1dWlkOjAwM2ExZGQ4LWE1ZDItNDJlZi04MTgyLWU5MjFjMGE5ZjJjZCIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJWZXJpZmlhYmxlQXR0ZXN0YXRpb24iXSwiaXNzdWVyIjoiZGlkOmtleTp6MmRtekQ4MWNnUHg4VmtpN0pidXVNbUZZcldQZ1lveXR5a1VaM2V5cWh0MWo5S2JzRGJWWlhkYjNqekNhZ0VTeVk0RUUyeDdZangzZ053Y3RvRXVSQ0tLRHJkTlAzSFBGdEc4UlR2QmlZU3RUNWdoQkhoSGl6SDJEeTZ4UXRXM1BkMlNlY2l6TDliMmp6RENNcjdLYTVjUkFXWkZ3dnF3QXR3VFQ3eGV0NzY5eTlFUmg2IiwidmFsaWRGcm9tIjoiMjAyNi0wMS0wOFQxNToxNzo1MVoiLCJ2YWxpZFVudGlsIjoiMjAyNi0wMi0wN1QxNToxODowMVoiLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDprZXk6ejJkbXpEODFjZ1B4OFZraTdKYnV1TW1GWXJXUGdZb3l0eWtVWjNleXFodDFqOUtic0VZdmRyanhNalE0dHBuamU5QkRCVHp1TkRQM2tubjZxTFpFcnpkNGJKNWdvMkNDaG9QamQ1R0FIM3pwRkpQNWZ1d1NrNjZVNVBxNkVoRjRuS25IekRuem5FUDhmWDk5blpHZ3diQWgxbzdHajFYNTJUZGhmN1U0S1RrNjZ4c0E1ciJ9LCJjcmVkZW50aWFsU2NoZW1hIjp7ImlkIjoiaHR0cHM6Ly9hcGktdGVzdC5lYnNpLmV1L3RydXN0ZWQtc2NoZW1hcy1yZWdpc3RyeS92My9zY2hlbWFzL3pCNXlMeTdHWGRaczFpYUo3d04ySzVtaHdaRFR4akVDTTJmRUxZRTczbXUzRSIsInR5cGUiOiJGdWxsSnNvblNjaGVtYVZhbGlkYXRvcjIwMjEifX0.c2UxEGTMtRGIad_F2xP9_SxyIvn8ABhGX9ItqpC5bLr2U4isFBzuFzhypt8How_IXKuxLXSDmDf0SvUrVUNCDg

Verifying JWTs

Prerequisites

Verify a VC JWT using the verifyCredentialJwt function:

import {
  verifyCredentialJwt,
  type VerifyCredentialOptions,
} from "@cef-ebsi/verifiable-credential/vcdm20.js";

const vcJwt =
  "eyJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDplYnNpOnp0VFlFeWRjUFEyU3JLb2doSHF4QmZLI0JFTmRqRGZhdGxLai11UW92WUpsT184U2pPY1ZIdmk2SHJYS0xLRUI3UG8iLCJ0eXAiOiJ2Yytqd3QifQ.eyJpYXQiOjE3Njc4ODU0ODEsIkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy9ucy9jcmVkZW50aWFscy92MiJdLCJpZCI6InVybjp1dWlkOjAwM2ExZGQ4LWE1ZDItNDJlZi04MTgyLWU5MjFjMGE5ZjJjZCIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJWZXJpZmlhYmxlQXR0ZXN0YXRpb24iXSwiaXNzdWVyIjoiZGlkOmVic2k6enRUWUV5ZGNQUTJTcktvZ2hIcXhCZksiLCJ2YWxpZEZyb20iOiIyMDI2LTAxLTA4VDE1OjE3OjUxWiIsInZhbGlkVW50aWwiOiIyMDI2LTAyLTA3VDE1OjE4OjAxWiIsImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiZGlkOmtleTp6MmRtekQ4MWNnUHg4VmtpN0pidXVNbUZZcldQZ1lveXR5a1VaM2V5cWh0MWo5S2JzRVl2ZHJqeE1qUTR0cG5qZTlCREJUenVORFAza25uNnFMWkVyemQ0Yko1Z28yQ0Nob1BqZDVHQUgzenBGSlA1ZnV3U2s2NlU1UHE2RWhGNG5Lbkh6RG56bkVQOGZYOTluWkdnd2JBaDFvN0dqMVg1MlRkaGY3VTRLVGs2NnhzQTVyIn0sImNyZWRlbnRpYWxTY2hlbWEiOlt7ImlkIjoiaHR0cHM6Ly9hcGktdGVzdC5lYnNpLmV1L3RydXN0ZWQtc2NoZW1hcy1yZWdpc3RyeS92My9zY2hlbWFzL3pCNXlMeTdHWGRaczFpYUo3d04ySzVtaHdaRFR4akVDTTJmRUxZRTczbXUzRSIsInR5cGUiOiJGdWxsSnNvblNjaGVtYVZhbGlkYXRvcjIwMjEifSx7ImlkIjoiaHR0cHM6Ly9hcGktdGVzdC5lYnNpLmV1L3RydXN0ZWQtc2NoZW1hcy1yZWdpc3RyeS92My9zY2hlbWFzL3o2TFpjZEhVUTkxdWlyeGl1cUtyWUZ6emM5WDR1QjNiVVlYREVrd1dleVptciIsInR5cGUiOiJGdWxsSnNvblNjaGVtYVZhbGlkYXRvcjIwMjEifV0sInRlcm1zT2ZVc2UiOnsicGFyZW50QWNjcmVkaXRhdGlvbiI6Imh0dHBzOi8vYXBpLXRlc3QuZWJzaS5ldS90cnVzdGVkLWlzc3VlcnMtcmVnaXN0cnkvdjUvaXNzdWVycy9kaWQ6ZWJzaTp6dFRZRXlkY1BRMlNyS29naEhxeEJmSy9hdHRyaWJ1dGVzLzU2Mjc2OTJkNzQyZDUxZThjNzNlN2E4MmI4OWM0ZDIyMDBlM2I4Yzc4NDIzYWVjYjg2NzMxNTNiYTc0ZWQ4YmEiLCJyb290QXV0aG9yaXNhdGlvbiI6Imh0dHBzOi8vYXBpLXRlc3QuZWJzaS5ldS90cnVzdGVkLWlzc3VlcnMtcmVnaXN0cnkvdjUvaXNzdWVycy9kaWQ6ZWJzaTp6dFRZRXlkY1BRMlNyS29naEhxeEJmSy9hdHRyaWJ1dGVzLzU2Mjc2OTJkNzQyZDUxZThjNzNlN2E4MmI4OWM0ZDIyMDBlM2I4Yzc4NDIzYWVjYjg2NzMxNTNiYTc0ZWQ4YmEiLCJ0eXBlIjoiQXR0ZXN0YXRpb25Qb2xpY3kifX0.YQbWkxheFKk7sK-H0OAePd6ismw_kJ3ITOBDa5W4u2eSWN1e65PylcEqLmD1Fw18ujv8hxIyTTDhf4pxOzAlVQ";

const options = {
  /**
   * Custom Axios request headers
   */
  // axiosHeaders?: RawAxiosRequestHeaders;
  /**
   * Time in seconds expanding the validity period of the JWT, both before "nbf" and after "exp". Default : 0 second.
   * Note: the did-jwt library uses a similar `skewTime` parameter with a default value of 5 minutes (300 seconds).
   */
  // clockSkew?: number;
  /**
   * Extra credentialSchema types. By default, the library only supports "FullJsonSchemaValidator2021" and "JsonSchema".
   * The library is not responsible for validating these extra types.
   */
  // extraCredentialSchemaTypes?: string[];
  /**
   * Determines whether to validate the accreditations of the VC issuer or not.
   * Validation is active by default.
   * @defaultValue false
   */
  // skipAccreditationsValidation?: boolean;
  /**
   * Determines whether to validate the credential subject or not
   * Validation is active by default.
   */
  // skipCredentialSubjectValidation?: boolean;
  /**
   * Determines whether to validate the credential status or not.
   * Validation is active by default.
   * @defaultValue false
   */
  // skipStatusValidation?: boolean;
  /**
   * Axios requests timeout (in milliseconds). Default: 15 seconds
   */
  // timeout?: number;
  /**
   * Unix timestamp. Optional comparison date. Default: current date and time.
   * For the credential to be valid, `validFrom` ≤ `validAt` ≤ `validUntil`.
   */
  // validAt?: number;
  /**
   * Determines whether or not to validate the issuer's accreditations when `termsOfUse` is missing.
   * @defaultValue false
   */
  // validateAccreditationWithoutTermsOfUse?: boolean;
} satisfies VerifyCredentialOptions;

const verifiedVc = await verifyCredentialJwt(vcJwt, config, options);

console.log(JSON.stringify(verifiedVc, undefined, 2));
/*
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2"
  ],
  "id": "urn:uuid:003a1dd8-a5d2-42ef-8182-e921c0a9f2cd",
  "type": [
    "VerifiableCredential",
    "VerifiableAttestation"
  ],
  "issuer": "did:ebsi:ztTYEydcPQ2SrKoghHqxBfK",
  "validFrom": "2026-01-08T15:17:51Z",
  "validUntil": "2026-02-07T15:18:01Z",
  "credentialSubject": {
    "id": "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r"
  },
  "credentialSchema": [
    {
      "id": "https://api-test.ebsi.eu/trusted-schemas-registry/v3/schemas/zB5yLy7GXdZs1iaJ7wN2K5mhwZDTxjECM2fELYE73mu3E",
      "type": "FullJsonSchemaValidator2021"
    },
    {
      "id": "https://api-test.ebsi.eu/trusted-schemas-registry/v3/schemas/z6LZcdHUQ91uirxiuqKrYFzzc9X4uB3bUYXDEkwWeyZmr",
      "type": "FullJsonSchemaValidator2021"
    }
  ],
  "termsOfUse": {
    "parentAccreditation": "https://api-test.ebsi.eu/trusted-issuers-registry/v5/issuers/did:ebsi:ztTYEydcPQ2SrKoghHqxBfK/attributes/5627692d742d51e8c73e7a82b89c4d2200e3b8c78423aecb8673153ba74ed8ba",
    "rootAuthorisation": "https://api-test.ebsi.eu/trusted-issuers-registry/v5/issuers/did:ebsi:ztTYEydcPQ2SrKoghHqxBfK/attributes/5627692d742d51e8c73e7a82b89c4d2200e3b8c78423aecb8673153ba74ed8ba",
    "type": "AttestationPolicy"
  }
}
*/

Verification process

The verification of the credentials is performed using the following process:

1. Header

• The alg property must be ES256, ES256K, or EdDSA.
• The kid property must contain the DID of the issuer and the fragment identifier allowing to know which verification method to use.

2. Basic properties in the payload

• If the iss claim is defined, it must not conflict with the VC issuer property.
• If the sub claim is defined, it must not conflict with the VC credentialSubject.id property.
• If the jti claim is defined, it must match with the VC id.
• If the iat claim is defined, it must be a valid timestamp.
• If the nbf claim is defined, it must be a valid timestamp.
• If the exp claim is defined, it must be a valid timestamp.

3. Signature

• The signature must be validated against the verification method from the DID document corresponding to the VC JWT kid header.

4. Extra validations to the VC payload

• Validation of @context.
• Validation of type.
• Validation of dates.

5. Issuer in Trusted Issuers Registry

If the issuer is a Legal Entity:

• The issuer must be registered in the Trusted Issuers Registry.

Additionally, if the VC is an attestation with accreditation:

• The VC must contain a termsOfUse property pointing to the accreditations of the issuer.
• The issuer must be accredited to issue the types present in the credential.

6. Credential subject

• The credential subject must be a valid DID, using either the did:ebsi v1 method (Legal Entity) or the did:key method (Natural Person).

7. Credential schema

• The VC credential schema(s) must link to valid EBSI credential schemas, registered in the Trusted Schemas Registry.
• The credential payload is validated against the aforementioned JSON Schemas.

Axios config defaults

The library uses the global axios instance to make HTTP requests. If needed, you can specify config defaults. More information on axios configuration can be found here.

For instance, if you want to override the default HTTPS agent with a custom agent using https-proxy-agent, you can do it like so:

import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

axios.defaults.httpsAgent = new HttpsProxyAgent("http://168.63.76.32:3128");

Try it online

The VC & VP validator tool uses the @cef-ebsi/verifiable-credential to verify VC JWTs.