SDK Overview

The TypeScript SDK is the supported server-side client for XKOVA customer operations. Its generated types, resource methods, API reference, and package artifact share one exact customer operation manifest. The current reviewed manifest contains 213 operations; the manifest entries, not that count, are authoritative.

Installation

npm install @xkova/sdk

Node 22 or newer is required. Use the package from a trusted backend, BFF, or server-side worker. Never put a tenant API key in browser code.

Create a tenant client

import { XKOVAClient } from '@xkova/sdk';

const client = XKOVAClient.forTenant({
  baseUrl: 'https://sandbox-api.xkova.com',
  apiKey: process.env.XKOVA_API_KEY,
  timeoutMs: 10_000,
});

const chains = await client.chains.listAvailable();
const assets = await client.workspaceTokens.list();

The API key determines tenant, workspace, and environment. It is the bearer authorization credential for every customer API request. Construct a separate client for each workspace key. The SDK does not publish partner-management, management Console, API-key lifecycle, controlled browser credential steps, provider administration, or browser capability operations. The customer-manifest member-auth operations are the supported confidential server protocol used by @xkova/sdk/member-bff; they are not exposed as a browser or raw-token interface.

Bearer authorization and production request signing

Every production workspace mutation requires both the bearer API key and an active asymmetric signing credential bound to the same API principal. The signing credential adds proof of possession and never replaces bearer authorization. Configure the credential UUID, registered algorithm, and an async callback that delegates to your KMS, HSM, or key provider. The private key never enters the SDK.

import { XKOVAClient } from '@xkova/sdk';

const client = XKOVAClient.forTenant({
  baseUrl: 'https://api.xkova.com',
  apiKey: process.env.XKOVA_API_KEY,
  requestSigner: {
    credentialId: process.env.XKOVA_SIGNING_CREDENTIAL_ID,
    algorithm: 'ecdsa-p256-sha256',
    async sign(input) {
      return customerKeyProvider.sign(input);
    },
  },
});

P-256 callbacks return 64-byte IEEE P1363 signatures. Ed25519 callbacks return 64 bytes. RSA callbacks use RSA-PSS with SHA-256, MGF1 SHA-256, and a 32-byte salt. XKOVA pins the algorithm to the credential resolved by keyid and omits the RFC 9421 alg parameter, because RFC 9421 does not register an rsa-pss-sha256 value. Signature lifetimes may be 30 through 60 seconds and default to 45.

The SDK emits Signature-Input and Signature using XKOVA's strict HTTP Message Signatures profile (RFC 9421). For a request body it emits the SHA-256 Content-Digest field defined by RFC 9530. The signature covers the exact final URL authority, encoded path and query, bearer authorization, body digest and content type, idempotency key, and all present routed or member-context headers. It serializes a JSON body once, signs those UTF-8 bytes, and sends the same string.

The API canonicalizes the incoming Host authority and requires it to match the configured public API origin before signature verification. A request delivered through another authority is rejected even when every other covered component is unchanged.

Request	Required credentials
Sandbox read or mutation	Bearer API key. Mutations are additionally signed only when a signer is configured.
Production read	Bearer API key only.
Production mutation	Bearer API key plus RFC 9421 asymmetric request signature.

A production mutation without a signer fails before fetch.

Each call uses a random nonce and a fresh short-lived signature. Explicit retries reuse the same caller-owned idempotency key and receive a new signature. Signing-credential registration and lifecycle remain private management operations and are not exposed by the customer SDK.

Customer namespaces

The client groups supported calls under accountHolders, branding, chains, contacts, escrows, feeSchedules, integrationGateways, onboarding, paymentRequests, payments, ramps, rwa, tenant, tokenization, transactions, wallets, webhooks, workspaceTokens, and workspaces.

const payments = await client.payments.list({ limit: 20 });
const contacts = await client.contacts.list({ limit: 20 });
const capTable = await client.rwa.capTable('ctk_...');

Hosted application administration

The tenant resource exposes the customer-controlled Hosted application lifecycle. XKOVA owns the fixed identity-provider security profile. Your server selects an existing same-workspace API principal, application name, enrollment mode, exact origins and callbacks, default status, and enabled state.

const application = await client.tenant.createHostedApplication({
  name: 'Acme Member App',
  api_key_id: 'key_...',
  enrollment_mode: 'invite_only',
  is_default: true,
});

await client.tenant.createAllowedOrigin({
  application_id: application.id,
  origin: 'https://app.example.com',
});
await client.tenant.createRedirectUrl({
  application_id: application.id,
  purpose: 'authorization_result',
  url: 'https://app.example.com/api/auth/callback',
});

const applications = await client.tenant.listMemberAuthApplications();
await client.tenant.updateHostedApplication(application.id, {
  enrollment_mode: 'open',
});
await client.tenant.disableHostedApplication(application.id);

The response includes the non-secret publishable application selector. These methods never expose identity-provider administrative configuration, provider tokens, provider client secrets, or signing keys.

BFF member context

Use the server-only @xkova/sdk/member-bff entry point for authorization transactions, provider-proof exchange, secure refresh rotation, exact-session logout, safe browser projections, CSRF, cookie directives, and framework-neutral session, authorization-transaction, and direct proof-exchange transaction store contracts. Account-holder self methods require an opaque XKOVA member-session ID and the exact non-secret publishable application key recovered from the BFF's server-side session. The one-time provider proof is consumed only during exchange and is never sent downstream. The session stays in the customer BFF, and the methods never accept an arbitrary account-holder ID.

import { XKOVAMemberBffClient } from '@xkova/sdk/member-bff';

const memberAuth = new XKOVAMemberBffClient({
  baseUrl: 'https://sandbox-api.xkova.com',
  apiKey: process.env.XKOVA_API_KEY,
  publishableKey: process.env.XKOVA_PUBLISHABLE_KEY,
});

const start = await memberAuth.beginHostedAuthorization({
  browserOrigin: 'https://app.example.com',
  redirectUri: 'https://app.example.com/api/auth/callback',
  transactionStore,
});

const balance = await client.accountHolders.selfBalance({
  memberSessionId: session.sessionId,
  memberAuthPublishableKey: session.applicationData.memberAuthPublishableKey,
});
await client.accountHolders.ensureSelfWalletProvisioning({
  memberSessionId: session.sessionId,
  memberAuthPublishableKey: session.applicationData.memberAuthPublishableKey,
});

The provisioning request has no body and accepts no account-holder, provider identity, address, chain, wallet, credential, or registration selector. Raw wallet derivation challenges and provider credentials are not part of the customer SDK.

The customer owns its application-session persistence, framework wiring, FI-specific identity integration, deployment environment, and the encryption and access controls for stored session and pending proof material. Callback recovery without provider-code re-redemption is guaranteed only after the authorization store durably persists stagedProviderExchange. From that point, callback recovery reuses the stable XKOVA operation attempt and application-session reference. Before durable staging, an ambiguous provider response or staging-store acknowledgement may invoke the provider exchange again and must be resolved by the provider adapter or a fresh authorization transaction. Direct proof exchange durably stages the supplied proof with its stable operation attempt before the first XKOVA exchange. Preserve callback state for failures known to occur after durable staging. Durable application cookies use Secure, HttpOnly, host-only __Host- naming and SameSite=Strict. A separate short-lived SameSite=Lax flow cookie is used only where an OAuth or OIDC callback requires it. See Authentication.

Reliability and helpers

Feature	Use
`timeoutMs` and `AbortSignal`	Bound transport calls and cancel workflow polling.
`withRetry()`	Apply caller-owned retry policy without automatic write retries.
`withIdempotency()`	Create a stable key to reuse for the same logical write.
`paginateCursor()`	Walk a cursor-paginated list.
`verifyWebhookSignature()`	Verify a webhook signature over the raw request body.

Errors and types

Non-success responses throw XKOVAApiError, including the public error code and correlation ID. Import customer-only generated types from @xkova/sdk/types. See the interactive customer reference for exact request and response schemas.

Was this helpful?