Authentication

XKOVA normalizes trusted provider proofs into scoped sessions without forcing every product through one XKOVA-hosted login experience. Authentication UX follows the product and identity owner. The common XKOVA boundary is proof verification, session exchange, scoped authorization, and business APIs.

Customer server credentials

Customer backends authenticate every customer API request with a workspace-scoped bearer credential.

Authorization: Bearer xkv_test_...

Prefix	Workspace mode	Use
xkv_test_	Sandbox	Sandbox customer API.
xkv_live_	Production	Production customer API after access approval.

Production mutations also require a customer-held asymmetric request-signing credential. Production reads remain bearer-authenticated by default. See Key Management and SDK Overview. API-key and signing-credential lifecycle operations are private management functions and are not published in @xkova/sdk.

Member identity entry points

Member authentication is product-specific. The person authenticates with the identity owner, then a confidential server presents a trusted proof to XKOVA. A visible visit to auth.xkova.com is required only when XKOVA owns an explicit authentication or security ceremony.

Product	Who authenticates the person	Proof presented to XKOVA	Visible XKOVA auth page
Consumer Xperience, BYO OIDC	The financial institution's IdP	Issuer and audience pinned OIDC proof, exchanged by the customer BFF	No
Consumer Xperience, Hosted Auth	XKOVA Hosted Auth	XKOVA Hosted Auth proof, exchanged by the customer BFF	Yes, for the Hosted Auth ceremony
Embedded Solution	Lumin, Q2, Banno, or another approved digital channel	Provider-specific launch or OIDC proof from an approved server-side adapter	No
Core Rails	The institution's staff IdP and staff platform	Institution staff SSO or a single-use contextual launch	No
XKOVA management Console	The existing private Console identity system	Private management session	Existing behavior is unchanged

BYO OIDC is the recommended enterprise member-auth model. The configured financial institution identity is authoritative for that tenant. XKOVA never treats email as identity equivalence, never links Hosted Auth and BYO identities automatically, and never accepts a provider proof for a different tenant, workspace, or application.

The confidential member-session exchange

A customer BFF calls the provider-neutral member-auth boundary after the identity provider has authenticated the member. Provider credentials and XKOVA refresh material stay server-side.

provider-specific proof
  -> POST /v1/member-auth/proof/challenges
  -> POST /v1/member-auth/proof/exchange
  -> scoped XKOVA member session in the BFF

Server-only helper operation	Purpose	Server credentials
POST /v1/member-auth/proof/challenges	Issue the one-time nonce bound to the next provider proof.	Workspace bearer plus publishable key
POST /v1/member-auth/proof/exchange	Verify and consume the provider proof, resolve an existing member binding, and create an XKOVA session.	Workspace bearer plus publishable key
POST /v1/member-auth/hosted/authorizations	Start the application-bound Hosted Auth ceremony with exact origin, callback, state, and PKCE binding.	Workspace bearer plus publishable key
POST /v1/member-auth/hosted/authorizations/exchange	Consume the one-time Hosted result and create the provider-neutral member session.	Workspace bearer plus publishable key
POST /v1/member-auth/refresh	Rotate the single-use XKOVA refresh credential.	Workspace bearer plus publishable key
GET /v1/member-auth/session	Validate the exact active session and return a safe member context.	Workspace bearer, publishable application key, and XKOVA member-session ID
POST /v1/member-auth/sign-out	Revoke the exact session by default.	Workspace bearer, publishable application key, and XKOVA member-session ID

These confidential operations are part of the customer manifest specifically so the supported @xkova/sdk/member-bff helper can implement the protocol. Customer browser code must not call them directly, and ordinary XKOVAClient resources do not expose them.

The X-XKOVA-Publishable-Key value is a non-secret application registration identifier. It selects the registered tenant, workspace, environment, application, provider kind, issuer, audience, origins, and redirect configuration only when it also matches the authenticated workspace principal. It grants no authority by itself and is not a substitute for the bearer credential.

The exchange accepts an exact registered provider proof only once. Ordinary member resource calls do not accept provider tokens, X-OIDC-ID-Token, X-End-User-Id, raw Hosted Auth sessions, or caller-selected account-holder IDs. They use the server-held XKOVA session through X-Member-Session-Id plus X-XKOVA-Publishable-Key, and the API rechecks its tenant, workspace, application, policy version, configuration version, and active account-holder binding.

Session creation transactionally rechecks the registered application and policy versions after proof verification. A concurrent trust change therefore rejects creation. Refresh validates the caller's exact tenant, workspace, application, publishable key, and API principal before consumed-token replay can revoke a family. Expired one-time proof bindings are retired only after their replay window ends.

Use the supported BFF helper

@xkova/sdk/member-bff implements the XKOVA side of authorization transactions, proof exchange, refresh rotation, exact-session logout, safe browser projection, CSRF binding, cookie directives, and framework-neutral session, authorization-transaction, and direct proof-exchange transaction store contracts. The customer supplies its own durable stores, web-framework wiring, FI-specific identity integration, and storage encryption and access controls.

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

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

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

The durable first-party application cookie is host-only through the __Host- prefix, Secure, HttpOnly, and SameSite=Strict. A separate short-lived SameSite=Lax flow cookie may carry OAuth or OIDC transaction state across a callback. Do not weaken the durable cookie for callback convenience. The BFF store must serialize refresh and logout for one session reference across every application instance. Callback recovery without provider-code re-redemption is guaranteed only after the authorization store durably persists stagedProviderExchange. From that point, the identical callback reuses the staged proof, stable XKOVA exchange attempt, and application-session reference. A bounded completed transaction also recovers a committed application session after response or store acknowledgement loss. Before durable staging, an ambiguous provider response or staging-store acknowledgement may invoke the provider exchange again. The provider adapter must resolve that ambiguity or fail closed and start a fresh authorization transaction. Preserve the flow cookie and durable transaction for failures known to occur after durable staging. XKOVAMemberAuthorizationTerminalError is the helper's authoritative terminal classification for the exact transaction.

A confidential proof that does not use the callback helper requires a stable customer-generated exchangeId and encrypted XKOVAMemberProofExchangeTransactionStore. Reuse the same exchange identifier until the helper returns the application session.

The browser package

@xkova/member is the optional browser companion for Consumer Xperience. It calls only the customer's same-origin BFF and never accepts an XKOVA API key, provider proof, session ID, access token, refresh token, or caller-supplied authorization header. Its initial self-service surface covers session launch and status, enrollment, safe profile and avatar, balances and history, consents, data exports, verification, self-wallet operations, and Account Center handoff. Contacts and money movement are not in the browser package.

Customer-server money movement remains available through the manifested @xkova/sdk operations. The browser exclusion does not remove deposits, withdrawals, payments, quotes, wallet activity, or signing workflows from the customer backend product.

Hosted Auth, BYO OIDC, and embedded channels

Hosted Auth

XKOVA Hosted Auth is an optional managed identity choice. Managed Hosted email is included for sandbox; production follows the active paid plan or Feature Access Code. Enable it in Console by selecting an existing same-workspace API principal, or by using the guided setup to create a dedicated member_auth-only BFF principal. Choose invite-only or open enrollment and register the exact application origin and authorization-result callback. Configure the brand once in the existing Branding settings. The generated publishable key is a non-secret application selector.

The controlled XKOVA page displays your brand, collects a six-digit email code, and challenges an existing TOTP factor when required. Your BFF starts the ceremony with beginHostedAuthorization and completes the one-time result with completeHostedAuthorization. XKOVA owns the provider endpoints, signing metadata, email delivery hook, and security profile. You do not configure another Hosted OAuth client ID or secret, issuer, JWKS URL, authorization URL, or token URL.

Hosted members manage passkeys, Hosted sessions, recovery-code readiness, and applicable wallet readiness in XKOVA's tenant-branded Account Center. The customer BFF starts a one-use, application-bound handoff. The handoff is context only, so the expected Hosted subject must authenticate before an Account Center session is issued. Lost-all-factor recovery requires one saved recovery code plus a fresh verified email code, replacement of provider factors, acknowledgement of a new code set, security notification acceptance, and a 24-hour restriction before fresh sign-in can restore authority. Do not recreate these ceremonies on the customer application origin.

Password login remains outside this Hosted integration. Hosted Auth and Account Center are not required for enterprise OIDC, Embedded Solution, or Core Rails.

BYO OIDC

The customer BFF owns state, nonce, PKCE, and the provider callback when using the supported BFF proof exchange pattern. A brokered flow may also be approved. Provider client secrets and refresh credentials never enter browser JavaScript. Issuer, audience, provider namespace, tenant, workspace, application, and callback are pinned to registered server configuration.

Plover Credit Union demonstrates Plover-branded Hosted email sign-in and one-click Quick Demo. Both paths complete the same one-time Hosted result and confidential BFF exchange. Neither identity path exposes an identity-provider credential or XKOVA member-session credential to browser JavaScript. FI/BYO OIDC remains a supported enterprise integration, but it is not a Plover customer-facing path.

Embedded Solution

Lumin, Q2, and Banno authenticate the member inside the institution's existing digital banking session. A thin platform adapter verifies the provider-specific launch or OIDC result and exchanges it for the same downstream XKOVA member-session model. Banno OIDC can use the normalized JWT proof boundary. Lumin and Q2 signed launches fail closed until their exact vendor signature, key discovery, replay, audience, and return contracts are registered. The shared embedded application is not required to adopt the external @xkova/member abstraction.

Staff and management users

Institution staff using Core Rails are not XKOVA management Console users. Core Rails uses institution staff SSO, a managed sidecar, or a signed contextual launch to create a server-managed staff context. The existing XKOVA management Console keeps its private authentication architecture. No authentication-host, issuer, JWKS, cookie, or redirect migration is implied by the member-session work.

Fresh Human Authorization For Member Actions

Payment signing, escrow signing, and member approval attestations freeze the exact operation and require a new, short-lived human proof before the controlled wallet-signing surface opens. Hosted Auth uses the member's Account Center passkey. FI/BYO OIDC uses a fresh provider proof that satisfies the application's pinned issuer, subject, maximum age, ACR, and AMR policy. XKOVA does not force the FI user through Hosted Auth or require an XKOVA passkey.

The BFF exchanges the one-use proof result for an opaque signing session. A returned signing_url is only a locator. It is not bearer authority, a member session, or customer request signing. Claim and verification capabilities remain separate purpose-bound flows.

Related

See Member Browser and BFF Integration, SDK Overview, Key Management, and the interactive customer reference.