Skip to main content

Quick Start

The basic patterns align with the Maven Central package README — create a client, authenticate, then call APIs.

Prerequisites

Complete Installation first — add the Maven dependency, set CANDESCENT_* credentials, and confirm the SDK loads.

Create a client​

import com.candescent.di.CandescentClient;
import com.candescent.di.ClientConfig;
import com.candescent.di.Environment;
import com.candescent.di.generated.model.AccountsResponse;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        try (CandescentClient client = new CandescentClient(new ClientConfig()
                .setClientId(System.getenv("CANDESCENT_CLIENT_ID"))
                .setClientSecret(System.getenv("CANDESCENT_CLIENT_SECRET"))
                .setInstitutionId(System.getenv("CANDESCENT_INSTITUTION_ID"))
                .setEnvironment(Environment.STAGE))) {

            AccountsResponse accounts = client.accounts()
                    .callList()
                    .hostUserId("user-12345")
                    .execute();
            int count = accounts.getAccounts() != null ? accounts.getAccounts().size() : 0;
            System.out.println("Found " + count + " accounts");
        }
    }
}

CandescentClient implements AutoCloseable — use try-with-resources or call close() when you are done to revoke cached OAuth tokens and release 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 com.candescent.di.CandescentClient;
import com.candescent.di.ClientConfig;
import com.candescent.di.Environment;

CandescentClient client = new CandescentClient(new ClientConfig()
        .setClientId("your-client-id")
        .setClientSecret("your-client-secret")
        .setInstitutionId("your-institution-id")
        .setEnvironment(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), sandbox
import com.candescent.di.CandescentClient;

CandescentClient client = CandescentClient.fromEnv();

See Installation for the full environment variable reference.

Option 3 — Static bearer token​

import com.candescent.di.CandescentClient;
import com.candescent.di.ClientConfig;

CandescentClient client = new CandescentClient(new ClientConfig()
        .setBearerToken("your-pre-obtained-jwt")
        .setInstitutionId("your-institution-id"));

Provide either CANDESCENT_BEARER_TOKEN or CANDESCENT_CLIENT_ID + CANDESCENT_CLIENT_SECRET.

Usage​

The client is organized by API service area. Each accessor on CandescentClient maps to one generated API class.

Accounts​

import com.candescent.di.generated.model.AccountsResponse;
import com.candescent.di.generated.model.Account;
import com.candescent.di.generated.model.TransactionsResponse;

// List accounts for a user
AccountsResponse accounts = client.accounts()
        .callList()
        .hostUserId("user-12345")
        .execute();

// Get a specific account
Account account = client.accounts()
        .callGet()
        .accountId("acc-abc123")
        .execute();

// List transactions for an account
TransactionsResponse txns = client.transactions()
        .callListTransactions()
        .accountId("acc-abc123")
        .hostUserId("user-12345")
        .execute();
tip

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

Business banking​

import com.candescent.di.generated.model.BusinessEntitlementsResponse;
import com.candescent.di.generated.model.BusinessDetailsResponse;

// Get business entitlements
BusinessEntitlementsResponse entitlements = client.entitlements()
        .callGetBusinessEntitlements()
        .businessId("biz-456")
        .execute();

// Look up business details by ID
BusinessDetailsResponse details = client.profile()
        .callGetBusinessDetails()
        .searchType("BUSINESS_ID")
        .searchValue("biz-456")
        .includeTins(true)
        .includeUsers(true)
        .execute();

Standalone operations (serverless / Lambda)​

For short-lived environments (such as AWS Lambda) where you do not want to create and close a client on every invocation, use per-operation helpers from com.candescent.di.operations — they read CANDESCENT_* environment variables and handle client setup internally.

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 examples for every API area
  3. Framework Integration — Spring Boot and Lambda patterns