Credentials

Retrieve, verify, and present W3C Verifiable Credentials and SD-JWT selective disclosures.

Overview

The credentials sub-client manages W3C Verifiable Credentials and SD-JWT selective disclosures. You can retrieve individual credentials, list credentials with filters, verify credential JWTs, and create selective-disclosure presentations.

// Get, list, verify, present
const vc = await grantex.credentials.get('vc_01HXYZ...');
const all = await grantex.credentials.list({ principalId: 'user_abc123' });
const verification = await grantex.credentials.verify(vcJwt);
const presentation = await grantex.credentials.present({ sdJwt, disclosedClaims: ['name', 'email'] });

---

credentials.get()

Retrieve a single Verifiable Credential by its ID.

const vc = await grantex.credentials.get('vc_01HXYZ...');

console.log(vc.id);           // 'vc_01HXYZ...'
console.log(vc.type);         // ['VerifiableCredential', 'IdentityCredential']
console.log(vc.issuer);       // 'did:web:grantex.dev'
console.log(vc.subject);      // 'did:grantex:user_abc123'
console.log(vc.issuanceDate); // '2026-03-01T00:00:00Z'
console.log(vc.status);       // 'active'
console.log(vc.jwt);          // compact JWT string

Parameters

credentialId · string · required

The unique credential identifier.

Response: VerifiableCredential

id · string

Unique credential identifier.

type · string[]

Credential types (always includes 'VerifiableCredential').

issuer · string

DID of the credential issuer.

subject · string

DID of the credential subject (the holder).

issuanceDate · string

ISO 8601 timestamp when the credential was issued.

expirationDate · string | null

ISO 8601 timestamp when the credential expires, or null if it does not expire.

status · string

Current status: 'active', 'revoked', or 'expired'.

jwt · string

The credential in compact JWT format.

claims · Record<string, unknown>

The credential subject claims (key-value pairs).

---

credentials.list()

List Verifiable Credentials with optional filters.

const result = await grantex.credentials.list({
  principalId: 'user_abc123',
  type: 'IdentityCredential',
  status: 'active',
  page: 1,
  pageSize: 20,
});

console.log(result.credentials.length); // 3
console.log(result.credentials.length); // 3 returned
for (const vc of result.credentials) {
  console.log(vc.id, vc.type);
}

Parameters

principalId · string

Filter credentials by principal (subject) ID.

type · string

Filter by credential type (e.g., 'IdentityCredential', 'EmploymentCredential').

status · 'active' | 'revoked' | 'expired'

Filter by credential status.

page · number

Page number for pagination (default: 1).

pageSize · number

Number of results per page (default: 20, max: 100).

Response: ListCredentialsResponse

credentials · VerifiableCredential[]

Array of Verifiable Credential objects.

total · number

Total number of matching credentials.

---

credentials.verify()

Verify a Verifiable Credential JWT. Checks the signature, expiration, revocation status, and issuer trust chain.

const result = await grantex.credentials.verify(vcJwt);

if (result.valid) {
  console.log(result.issuer);    // 'did:web:grantex.dev'
  console.log(result.subject);   // 'did:grantex:user_abc123'
  console.log(result.claims);    // { name: 'Alice', email: '[e-mail]' }
  console.log(result.expiresAt); // '2027-03-01T00:00:00Z'
} else {
  console.log(result.reason);    // 'expired' | 'revoked' | 'invalid_signature'
}

Parameters

vcJwt · string · required

The Verifiable Credential in compact JWT format.

Response: VerifyCredentialResponse

valid · boolean

Whether the credential is valid.

issuer · string

DID of the credential issuer (present when valid).

subject · string

DID of the credential subject (present when valid).

claims · Record<string, unknown>

The credential subject claims (present when valid).

expiresAt · string | null

ISO 8601 expiration timestamp, or null if the credential does not expire.

reason · string

Reason for invalidity (present when valid is false): 'expired', 'revoked', 'invalid_signature', or 'untrusted_issuer'.

---

credentials.present()

Create a selective-disclosure presentation from an SD-JWT. Only the specified claims are disclosed in the resulting presentation JWT.

const presentation = await grantex.credentials.present({
  sdJwt: 'eyJ0eXAiOiJ2YytzZC1qd3QiLC...',
  disclosedClaims: ['name', 'email'],
});

console.log(presentation.presentationJwt);   // compact JWT with selective disclosures
console.log(presentation.disclosedClaims);   // ['name', 'email']
console.log(presentation.holderBinding);     // key binding JWT

Parameters

sdJwt · string · required

The SD-JWT credential to create a presentation from.

disclosedClaims · string[] · required

List of claim names to disclose in the presentation. All other claims remain hidden.

audience · string

The intended verifier DID or URL. Included in the holder binding JWT if provided.

nonce · string

A nonce value for replay protection in the holder binding.

Response: PresentCredentialResponse

presentationJwt · string

The SD-JWT presentation containing only the disclosed claims.

disclosedClaims · string[]

The claim names that were disclosed.

holderBinding · string

The key binding JWT proving the holder’s possession of the credential.

---

Full example

import { Grantex } from '@grantex/sdk';

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

// List active credentials for a user
const { credentials } = await grantex.credentials.list({
  principalId: 'user_abc123',
  status: 'active',
});

// Verify a specific credential
const vc = credentials[0];
const verification = await grantex.credentials.verify(vc.jwt);
if (!verification.valid) {
  throw new Error(`Credential invalid: ${verification.reason}`);
}

// Create a selective-disclosure presentation for a verifier
const presentation = await grantex.credentials.present({
  sdJwt: vc.jwt,
  disclosedClaims: ['name', 'email'],
  audience: 'did:web:verifier.example.com',
  nonce: 'unique-request-nonce',
});

// Send presentation.presentationJwt to the verifier