SDK Reference

Reference for com.candescent.forge:di-java-sdk — client configuration, authentication, service areas, pagination, errors, and packages.

For HTTP-level operation details, use the API Reference. For runnable examples per API area, see Examples.

CandescentClient

Constructor

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

CandescentClient client = new CandescentClient(new ClientConfig()
        .setClientId("...")
        .setClientSecret("...")
        .setInstitutionId("...")
        .setEnvironment(Environment.STAGE)  // optional; default STAGE
        .setBaseUrl("https://custom.api.host"));  // optional override

Field	Required	Description
clientId	Yes*	OAuth client ID
clientSecret	Yes*	OAuth client secret
institutionId	Yes	Institution identifier
bearerToken	Yes*	Static JWT (skips OAuth flow)
username / password	No	Password grant (with client credentials)
tokenProvider	No	Custom TokenProvider implementation
environment	No	Environment.SANDBOX, Environment.STAGE, or Environment.PRODUCTION
baseUrl	No	Override API base URL (advanced)

Provide clientId + clientSecret, bearerToken, or tokenProvider.

See Quick Start → Create a client for a code example.

CandescentClient.fromEnv()

Reads CANDESCENT_* environment variables. See Installation.

Lifecycle

Always call client.close() on shutdown (or use try-with-resources) to revoke cached tokens and release resources.

try (CandescentClient client = CandescentClient.fromEnv()) {
    // ... API calls
}

Service areas

CandescentClient exposes generated API classes as accessors. Map them to API Reference tag groups:

Client accessor	API area	Docs tag group
oAuthV1(), oAuthV2()	Authentication	Authentication
registrationAndAccess(), profileAndStatus(), contactInfo()	Customer registration, profile, contact	Customer Management
accounts(), transactions(), bankingActivities(), images()	Accounts and transactions	Core Banking
entitlements(), payments(), registration()	Business banking	Business Banking
recipients(), transfers()	Recipients and transfers	Money Movement
systemAlerts(), institutionAlerts(), templates(), userPreferences(), institutionPreferences(), historyAndEvents()	Alerts	Alerts and Notifications
institutionDisclosures(), userDisclosures(), electronicStatements()	Disclosures and e-statements	Documents and Preferences
experienceGroups(), jobs(), promotionsSuite(), audience()	Campaigns and jobs	Customer Campaigns
mxPlatform(), realTime(), sso(), reporting()	MX integration	MX
notificationChannels()	Subscriptions and events	Notification Channels

See Quick Start → Usage for Accounts and Business Banking examples. Additional service area examples:

Customer management

// Register a new customer
RegisterCustomerResponse response = client.registrationAndAccess()
        .callRegister()
        .body(registerRequest)
        .execute();

// Reset password
client.registrationAndAccess()
        .callResetPassword()
        .body(resetPasswordRequest)
        .execute();

Money movement

// List recipients for a user
RecipientsResponse recipients = client.recipients()
        .callListRecipients()
        .hostUserId("user-12345")
        .execute();

// Get a specific recipient
Recipient recipient = client.recipients()
        .callGetRecipient()
        .recipientId("rec-abc123")
        .hostUserId("user-12345")
        .execute();

Notification channels

// List institution-level subscriptions
SubscriptionsResponse subs = client.notificationChannels()
        .callListInstitutionSubscriptions()
        .execute();

// Get a specific subscription
Subscription sub = client.notificationChannels()
        .callGetSubscription()
        .subscriptionId("sub-xyz")
        .execute();

Import request/response types from com.candescent.di.generated.model.

Standalone operations

For serverless functions or one-off scripts, use per-operation helpers from com.candescent.di.operations instead of CandescentClient. See Quick Start → Standalone operations and Framework Integration.

Operation registry

The SDK ships an operation registry that maps every API operation to its tag group, tag, HTTP method, path, and SDK accessor:

import com.candescent.di.registry.OperationRegistry;

Use it to enumerate available operations programmatically or build tooling that inspects the API surface at runtime.

Pagination

List endpoints support PageIterator — a synchronous iterable that fetches subsequent pages:

import com.candescent.di.pagination.PageIterator;

PageIterator<Account> pages = new PageIterator<>(
        (page, size) -> client.accounts()
                .callList()
                .hostUserId("user-12345")
                .page(page)
                .size(size)
                .execute()
                .getAccounts(),
        0,
        50);

for (Account account : pages) {
    System.out.println(account.getAccountId());
}

Omit size to use the API default page size (typically 25).

Error handling

Generated API methods throw com.candescent.di.generated.ApiException. Map to typed SDK exceptions:

import com.candescent.di.CandescentClient;
import com.candescent.di.generated.ApiException;
import com.candescent.di.errors.NotFoundException;
import com.candescent.di.errors.RateLimitException;
import com.candescent.di.errors.AuthenticationException;

try {
    client.accounts()
            .callGet()
            .accountId("missing")
            .execute();
} catch (ApiException ex) {
    var error = CandescentClient.mapException(ex);
    if (error instanceof NotFoundException) {
        // 404
    } else if (error instanceof RateLimitException rateLimit) {
        System.out.println("Retry after " + rateLimit.getRetryAfter());
    } else if (error instanceof AuthenticationException) {
        // 401 — check credentials
    } else {
        System.out.println(error.getStatusCode() + ": " + error.getMessage());
    }
}

HTTP status	Exception class
Any non-2xx	ApiErrorException (base)
400	BadRequestException
401	AuthenticationException
403	PermissionDeniedException
404	NotFoundException
409	ConflictException
422	UnprocessableEntityException
429	RateLimitException
5xx	InternalServerErrorException

Retry behavior

The SDK retries transient failures with exponential backoff:

Retried status codes	Max retries	Initial delay	Max delay
408, 429, 500, 502, 503, 504	2 (3 total attempts)	500ms	30s

RateLimitException is thrown only after retries are exhausted.

Validation

Some parameters are mutually exclusive. For example, hostUserId and loginId cannot be set on the same accounts request. When the SDK detects a constraint violation, it throws an error before making the HTTP call.

Versioning

The SDK package version and OpenAPI specification version are tracked independently.

SDK package	com.candescent.forge:di-java-sdk 1.0.0
OpenAPI spec	1.8.0

When the OpenAPI spec changes, a new SDK release is generated from the updated spec.