TypeScript SDK Examples

Code examples for common operations using @idunion/tl-sdk.

Setup

Install the SDK and instantiate the client. The DefaultApi class accepts a Configuration object and an optional base path.

import { DefaultApi } from "@idunion/tl-sdk";

const tlClient = new DefaultApi(
  { isJsonMime: () => true },
  process.env.TL_API_URL,
);

All write operations require a bearer token passed via Axios request options. Read operations on public endpoints (e.g. fetching the ETSI XML) do not require authentication.

const authHeader = (token: string) => ({
  headers: { Authorization: `Bearer ${token}` },
});

Trust List Creation

Create a new Trust List by providing its name, description, the governance wallet, the verifier used for onboarding credential verification, and the list type.

import { DefaultApi, TlPayload, TlType } from "@idunion/tl-sdk";

const tlPayload: TlPayload = {
  name: "My Wallet Provider Trust List",
  description: "Trust List for certified wallet providers under the EUDIW framework",
  governanceWalletId: "wallet-abc123",   // wallet used for VC interactions
  verifierId: "verifier-xyz456",         // verifier that checks onboarding credentials
  type: TlType.WalletProvider,           // one of the TlType enum values
};

const { data: tl } = await tlClient.tlCreate(tlPayload, authHeader(token));

console.log("Created TL:", tl.id, tl.didBase);

Available TlType values:

Value	Description
`TlType.WalletProvider`	Wallet Provider
`TlType.QeaaProvider`	QEAA Provider
`TlType.PuBeaaProvider`	PuB-EAA Provider
`TlType.EaaProvider`	EAA Provider
`TlType.PidProvider`	PID Provider
`TlType.AccessCertificateAuthority`	Access Certificate Authority
`TlType.RegistrationCertificatesProvider`	Provider of Registration Certificates

Direct Onboarding

In the direct onboarding flow the Trust List operator creates a Trust List Record (TLR) on behalf of the applicant. The applicant provides a CSR and organisation details out-of-band; the operator submits them via tlrCreate.

See Direct Onboarding via the API for the full walkthrough, including authentication, the supported key material and how to verify, revoke and remove the record.

import { DefaultApi, TlrCreatePayload } from "@idunion/tl-sdk";

const tlId = "my-trust-list-id";

const payload: TlrCreatePayload = {
  // applicant's Certificate Signing Request (PEM-encoded)
  csr: "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",

  // organisation details
  orgName: "Example GmbH",
  orgTradeName: "Example",
  orgStreetAddress: "Musterstraße 1",
  orgCity: "Berlin",
  orgState: "Berlin",
  orgPostalCode: "10115",
  orgCountry: "DE",
  orgEmail: "contact@example.com",
  orgPhone: "+49 30 123456",
  orgWebAddress: "https://example.com",
  orgToC: "https://example.com/terms",

  // wallet solution details (for Wallet Provider TLs)
  walletSolutionName: "Example Wallet",
  walletSolutionRefId: "wallet-ref-001",
  walletSolutionUrl: "https://wallet.example.com",
};

const { data: tlr } = await tlClient.tlrCreate(tlId, payload, authHeader(token));

console.log("Created TLR:", tlr.id, tlr.did, tlr.status);

Onboarding via Verifiable Credential

The VC-based onboarding flow uses OID4VP. The operator initiates a session; the applicant scans a QR code and presents their Onboarding Credential. The operator polls for completion.

1. Initiate the onboarding session

import { DefaultApi, OnboardingPayload, OnboardingResponse } from "@idunion/tl-sdk";

const tlId = "my-trust-list-id";

const payload: OnboardingPayload = {
  verifierId: "verifier-xyz456",         // verifier configured on the TL
  holderEntityId: "did:key:z6Mk...",     // optional: pre-known did:key of the applicant
};

const { data: session } = await tlClient.onboardingInit(tlId, payload, authHeader(token));

// session.verifierState — opaque state token used to poll status
// session.verifierUrl  — OID4VP presentation request URL (encode as QR code for the applicant)
console.log("Onboarding session started:", session.verifierState);
console.log("QR code URL:", session.verifierUrl);

2. Poll for status

Poll onboardingStatus using the verifierState returned in step 1. The applicant scans the QR code and presents their credential in their wallet; the status transitions from in_progress to completed (or error).

import { OnboardingStatus, OnboardingStatusStatusEnum } from "@idunion/tl-sdk";

function pollOnboardingStatus(
  verifierState: string,
  intervalMs = 5000,
): Promise<OnboardingStatus> {
  return new Promise((resolve, reject) => {
    const timer = setInterval(async () => {
      const { data: status } = await tlClient.onboardingStatus(verifierState);

      switch (status.status) {
        case OnboardingStatusStatusEnum.Completed:
          clearInterval(timer);
          // status.did contains the newly registered DID
          resolve(status);
          break;

        case OnboardingStatusStatusEnum.Error:
          clearInterval(timer);
          reject(new Error(status.message ?? "Onboarding failed"));
          break;

        case OnboardingStatusStatusEnum.InProgress:
          // keep polling
          break;
      }
    }, intervalMs);
  });
}

const result = await pollOnboardingStatus(session.verifierState);
console.log("Onboarding complete. DID:", result.did);

Getting Trust List Records

All records for a Trust List

import { DefaultApi, TlrList, TlrStatusEnum } from "@idunion/tl-sdk";

const tlId = "my-trust-list-id";

const { data: tlrList } = await tlClient.tlrsGet(tlId, authHeader(token));

// tlrList.items — array of Tlr objects
for (const tlr of tlrList.items) {
  console.log(tlr.orgName, tlr.did, tlr.status);
}

// Filter by status
const trusted = tlrList.items.filter(
  (tlr) => tlr.status === TlrStatusEnum.Trusted,
);

TlrStatusEnum values:

Value	Meaning
`TlrStatusEnum.Onboarded`	Onboarded via a VC (issuer not verified by IDunion SCE)
`TlrStatusEnum.Trusted`	Onboarded via a VC whose issuer is verified by IDunion SCE
`TlrStatusEnum.Revoked`	Verification Method was revoked
`TlrStatusEnum.Expired`	Verification Method or Onboarding VC has expired

Single record

const tlrId = "some-tlr-id";

const { data: tlr } = await tlClient.tlrGet(tlId, tlrId, authHeader(token));

console.log(tlr.orgName, tlr.did, tlr.isRoot, tlr.status);

Search across all Trust Lists by organisation name

const { data: results } = await tlClient.tlrSearch("Example GmbH");

for (const tlr of results.items) {
  console.log(tlr.tlName, tlr.orgName, tlr.did);
}

Getting the Trust List in XML Format

The SDK exposes etsiTlGet which returns the ETSI TS 119 602 Trust List as a structured object. To download the raw XML file, construct the URL from the didBase field of the Trust List.

Via SDK method

const tlId = "my-trust-list-id";

const { data: etsiTl } = await tlClient.etsiTlGet(tlId);

// etsiTl is the ETSI Trust List as a parsed object
console.log(etsiTl);

Direct XML URL from `didBase`

The Tl object returned by tlCreate / tlGet includes a didBase field (a did:web DID). Convert it to an HTTPS base URL and append the ETSI path to get the XML download link.

import { DefaultApi, Tl } from "@idunion/tl-sdk";

function tlXmlUrl(tl: Tl): string {
  let host = tl.didBase
    .replace("did:web:", "")
    .replaceAll(":", "/");
  host = decodeURIComponent(host);
  const schema = host.startsWith("localhost") ? "http://" : "https://";
  return `${schema}${host}/etsi/119_602_tl.xml`;
}

const { data: tl } = await tlClient.tlGet(tlId, authHeader(token));

const xmlUrl = tlXmlUrl(tl);
console.log("XML download URL:", xmlUrl);
// e.g. https://tl.example.com/my-trust-list-id/etsi/119_602_tl.xml

Setup​

Trust List Creation​

Direct Onboarding​

Onboarding via Verifiable Credential​

1. Initiate the onboarding session​

2. Poll for status​

Getting Trust List Records​

All records for a Trust List​

Single record​

Search across all Trust Lists by organisation name​

Getting the Trust List in XML Format​

Via SDK method​

Direct XML URL from didBase​