Local Development

XKOVA is hosted, so there is nothing to install or run locally. Developing your integration means pointing your own app at the hosted sandbox with a test key and building the way you normally would.

Point your app at the sandbox

The sandbox API, management Console, and demo tenant all run on XKOVA's side, so you only need two values to start: the sandbox base URL and a sandbox API key (xkv_test_ prefix, issued from the console under Settings). Keep the key server-side, in your environment config.

XKOVA_BASE_URL=https://sandbox-api.xkova.com/v1
XKOVA_API_KEY=xkv_test_...   # server-side only

The SDK takes the same two values; see the SDK Overview. Sandbox keys only work against the sandbox, so local work can't reach production. Request signing is optional for sandbox mutations. Configure a sandbox signing credential only when you want to exercise the same RFC 9421 transport profile that production mutations require.

Develop a member experience through your backend

Consumer Xperience browser applications use your backend or BFF as the security boundary. Register the application and keep the resulting XKOVA and identity-provider session material on the server. A publishable key identifies the registered application and is not a secret or a source of member authority.

XKOVA_PUBLISHABLE_KEY=xkova_pk_sandbox_...  # public application identifier

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

The helper handles the XKOVA transaction, proof exchange, session refresh and rotation, exact-session logout, CSRF integration points, and safe member projections. Your application supplies its session store, web-framework wiring, and FI-specific identity integration. Use a host-only, Secure, HttpOnly, SameSite=Strict durable application cookie. If an OAuth or OIDC callback requires cross-site navigation, keep that state in a separate short-lived SameSite=Lax flow cookie. Never place provider tokens or XKOVA access or refresh credentials in browser JavaScript.

BYO OIDC is the recommended enterprise member-authentication model. XKOVA Hosted Auth is an optional managed alternative. For Hosted Auth, configure the application, branding, exact origin, and callback in Console, then call beginHostedAuthorization and completeHostedAuthorization from your BFF. XKOVA owns the controlled email-code and TOTP ceremony, provider endpoints, and signing metadata. Embedded Solution integrations accept authenticated Lumin, Q2, Banno, or another approved channel proof through a server-side adapter and do not require a universal XKOVA login page. See Authentication and Build a Member Experience.

Receive webhooks on your machine

XKOVA needs to reach your webhook endpoint, and a plain localhost URL isn't reachable from the internet. Two ways to develop the receiving side locally:

Test sends and replay. Register your endpoint in the console's Webhooks area, send a signed test event to it on demand, and replay any failed delivery. This covers most receiver development without extra tooling.
A public tunnel. To exercise live event flow end to end, expose your local receiver through a tunneling tool and register the tunnel URL as the endpoint.

Verify the signature on each delivery; the SDK ships a verifier. See Webhooks.

Test value and scenarios

Test tokens. Active test networks and test assets appear automatically. Read GET /v1/chains/available and GET /v1/workspace-tokens, then select a compatible asset for the operation. No real funds are involved.
Screening scenarios. The sandbox screening provider is deterministic: specific inputs produce allow, review, and block outcomes, so you can exercise each compliance path. See Screening.
The demo tenant. A populated, periodically reset tenant for exploring the management Console immediately and the Plover member surface through branded email sign-in or Quick Demo. See Try the Demos.

A few habits that help

Send an Idempotency-Key on every write; a re-run of a crashed script won't double-create. See Idempotency.
The sandbox uses tighter rate limits than production, so you can build in back-off early. See Rate Limits.
Log the correlation_id from each response and webhook; it ties your logs to XKOVA's audit trail if you need support. See Errors.

Follow the Quickstart to your first confirmed payment, or open Try the Demos for the management and Plover member views.

Was this helpful?