Skip to main content

Quick Start

The basic patterns align with the @cdx-forge/di-typescript-sdk README — create a client, authenticate, then call APIs.

Prerequisites

Complete Installation first — install the package, set CANDESCENT_* credentials, and confirm the SDK loads.

Create a client​

import { CandescentClient, Environment } from "@cdx-forge/di-typescript-sdk";

const client = new CandescentClient({
  clientId: process.env.CANDESCENT_CLIENT_ID!,
  clientSecret: process.env.CANDESCENT_CLIENT_SECRET!,
  institutionId: process.env.CANDESCENT_INSTITUTION_ID!,
  environment: Environment.Stage, // or Environment.Production
});

const accounts = await client.accounts.list({ hostUserId: "user-12345" });
console.log(`Found ${accounts.accounts?.length ?? 0} accounts`);

await client.close();

Call await client.close() when you are done — this revokes cached OAuth tokens and releases resources.

Authentication​

Obtain your Client ID, Client Secret, and Institution ID from the Developer Console quickstart guide.

Option 1 — OAuth 2.0 client credentials (recommended)​

import { CandescentClient, Environment } from "@cdx-forge/di-typescript-sdk";

const client = new CandescentClient({
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  institutionId: "your-institution-id",
  environment: Environment.Production,
});

The SDK obtains and caches OAuth tokens automatically, refreshes them before expiry, and injects the Authorization header on every request.

Option 2 — Environment variables​

Bash
export CANDESCENT_CLIENT_ID=your-client-id
export CANDESCENT_CLIENT_SECRET=your-client-secret
export CANDESCENT_INSTITUTION_ID=your-institution-id
export CANDESCENT_ENVIRONMENT=production  # or stage (default)
import { CandescentClient } from "@cdx-forge/di-typescript-sdk";

const client = CandescentClient.fromEnv();
note

Node.js does not load .env files automatically. Run source .env before your script, or use a library like dotenv. See Installation.

Option 3 — Static bearer token​

import { CandescentClient } from "@cdx-forge/di-typescript-sdk";

const client = new CandescentClient({
  bearerToken: "your-pre-obtained-jwt",
  institutionId: "your-institution-id",
});

Provide either CANDESCENT_BEARER_TOKEN or CANDESCENT_CLIENT_ID + CANDESCENT_CLIENT_SECRET. See Installation for the full environment variable reference.

Usage​

The client is organized by API service area. Each property on client maps to one group of operations.

Accounts​

// List accounts for a user
const accounts = await client.accounts.list({ hostUserId: "user-12345" });

// Get a specific account
const account = await client.accounts.get({ accountId: "acc-abc123" });

// List transactions for an account
const txns = await client.accounts.listTransactions({
  accountId: "acc-abc123",
  hostUserId: "user-12345",
});
tip

Pass either hostUserId or loginId on each request — not both.

Business banking​

// Get business entitlements
const entitlements = await client.entitlements.getBusinessEntitlements({
  businessId: "biz-456",
});

// Look up business details by ID
const details = await client.profile.getBusinessDetails({
  searchType: "BUSINESS_ID",
  searchValue: "biz-456",
  includeTins: true,
  includeUsers: true,
});

Standalone functions (serverless / Lambda)​

For environments where managing a client lifecycle is inconvenient:

import { listAccounts, getAccount, listTransactions } from "@cdx-forge/di-typescript-sdk/operations";

// Reads credentials from process.env.CANDESCENT_*
const accounts = await listAccounts({ hostUserId: "user-12345" });
const account = await getAccount({ accountId: "acc-abc123" });

See Framework Integration for Lambda patterns. For error handling and pagination, see SDK Reference.

Next steps​

  1. SDK Reference — service areas, standalone operations, retries, and versioning
  2. Examples — runnable scripts for every API area in cdx-typescript-sdk
  3. Framework Integration — Express, Fastify, and Lambda patterns