API Reference

Complete reference for everything exported by @nexla/react-sdk.

---

NexlaConnectProvider

The root provider. Must wrap all SDK hooks and components. Handles authentication, credential fetching, and end-user scoping.

import { NexlaConnectProvider } from '@nexla/react-sdk';

<NexlaConnectProvider
  serviceKey="YOUR_SERVICE_KEY"
  connectors={['CONNECTOR_KEY_1', 'CONNECTOR_KEY_2']}
  applicationId="YOUR_APPLICATION_ID"
  endUserId="YOUR_END_USER_ID"
>
  {/* your app */}
</NexlaConnectProvider>

Prop	Type	Required	Description
serviceKey	string	Yes	Service key from your SDK Application
connectors	string[]	Yes	Connector keys to enable
applicationId	string	Yes	ID of your registered SDK application. Validated against the service key at startup — throws APPLICATION_MISMATCH on mismatch.
endUserId	string	Yes	Your end user's ID (any stable string up to 128 chars). Stamped on new credentials; used to filter the credential list so each user sees only their own.
apiBaseUrl	string	—	Nexla Admin API base URL. Default: https://dataops.nexla.io/admin-api
onConnect	(credential: Credential) => void	—	Called after a credential is successfully created
onError	(error: NexlaConnectError) => void	—	Called on any SDK error
theme	ThemeConfig	—	Color scheme and primary color override
locale	string	—	BCP 47 locale tag (e.g. 'en-US')
children	React.ReactNode	Yes

---

NexlaThemeProvider

Injects CSS variables for all styled components. Must be inside NexlaConnectProvider. Only needed when using styled components.

import { NexlaThemeProvider } from '@nexla/react-sdk';

<NexlaThemeProvider mode="light">
  {/* styled components */}
</NexlaThemeProvider>

Prop	Type	Default	Description
mode	'light' | 'dark'	'light'	Color scheme
children	React.ReactNode	—

---

Hooks

useNexlaConnect()

Returns the full context state and all available actions.

const ctx = useNexlaConnect();

State

Property	Type	Description
credentials	Credential[]	Connected credentials for enabled connectors, scoped to applicationId and endUserId
connectors	Connector[]	Connector metadata for all enabled connectors
loading	boolean	true during initial fetch (session exchange + credentials + connectors)
error	NexlaConnectError | null	Last error (load, connect, or auth)
connectingConnector	string | null	Connector key currently mid-OAuth, or null
config	NexlaConnectConfig	Read-only provider config snapshot

Actions

Method	Signature	Description
connect	(connectorKey: string) => Promise<Credential>	Launch OAuth popup for a connector. Resolves with the created Credential.
disconnect	(credentialId: number) => Promise<void>	Delete a credential by ID
createCredential	(body: unknown) => Promise<Credential>	Create a credential via raw API body. Automatically stamps endUserId.
updateCredential	(id: number, body: unknown) => Promise<Credential>	Update an existing credential
refreshCredentials	() => Promise<void>	Re-fetch all credentials from the API
probeCredential	(id: number) => Promise<ProbeResult>	Test whether a credential's connection is still valid
fetchConnectorDetail	(connectorKey: string) => Promise<Connector | null>	Fetch the full expanded connector record
fetchConnectorAuthFields	(connectorKey: string) => Promise<ConnectorAuthField[]>	Fetch auth form fields for a connector
fetchCredentialDetail	(id: number) => Promise<Credential>	Fetch a single credential with config expanded

interface ProbeResult {
  isValid: boolean;
  message?: string;
}

---

useCredentials(connectorKey?)

Convenience hook for reading credentials, optionally filtered by connector.

const { credentials, loading, error, refresh } = useCredentials();
const { credentials: filtered } = useCredentials('CONNECTOR_KEY');

Property	Type	Description
credentials	Credential[]	Credentials, filtered to connectorKey if provided
loading	boolean	true during initial load
error	NexlaConnectError | null	Last fetch error
refresh	() => Promise<void>	Re-fetch from API

---

useConnectorForm(connectorKey)

Headless hook for building custom credential forms. Manages fields, values, validation, OAuth, and submission.

const form = useConnectorForm('CONNECTOR_KEY');

Loading & errors

Property	Type	Description
loading	boolean	true while connector fields are being fetched
error	NexlaConnectError | null	Load or submit error

Auth templates — connectors with multiple auth methods (e.g. "OAuth" and "API Key"):

Property	Type	Description
authTemplates	AuthTemplate[]	Available auth methods
selectedTemplateId	number | null	Currently selected template ID
setTemplate	(id: number) => void	Switch auth method and reset form

Form fields

Property	Type	Description
fields	ConnectorSpecAuthField[]	Visible, renderable fields (pre-filtered: hidden, OAuth-internal, and button fields excluded)
allFields	ConnectorSpecAuthField[]	All fields including hidden/internal
values	Record<string, unknown>	Current form values
setValue	(name: string, value: unknown) => void	Update a field value. Automatically applies conditional-default side effects.
errors	Record<string, string>	Validation error messages keyed by field name
validate	() => boolean	Validate all visible required fields. Populates errors. Returns true if valid.

Credential state

Property	Type	Description
existingCredential	Credential | undefined	Existing credential for this connector (current user), or undefined if creating new

OAuth

Property	Type	Description
isOAuth	boolean	true if the current connector/template uses OAuth
authorizing	boolean	true while OAuth popup is open
isAuthorized	boolean	true after successful authorize()
oauthError	string | null	Error message from the last authorize() attempt
authorize	() => Promise<void>	Open the OAuth popup. On success, sets isAuthorized = true and stores the payload for submit().

Submission

Property	Type	Description
submit	() => Promise<Credential>	Create or update the credential. Calls updateCredential when existingCredential exists, createCredential otherwise. For OAuth connectors, uses the payload from authorize().
reset	() => void	Clear all form values, errors, and OAuth state

---

useNexlaSnackbar()

Convenience hook that manages toast notification state and provides pre-built handlers for SDK callbacks.

const snackbar = useNexlaSnackbar();

Property	Type	Description
snackbarProps	NexlaSnackbarProps	Spread onto <NexlaSnackbar> — contains open, type, message, onClose
show	(message: string, type?: 'success' | 'error' | 'warning') => void	Programmatically show a toast
hide	() => void	Dismiss the current toast
onConnect	(credential: Credential) => void	Pass to NexlaConnectProvider.onConnect — shows success toast
onError	(error: NexlaConnectError) => void	Pass to NexlaConnectProvider.onError — shows error toast
onProbeError	(credential: Credential, message: string | null) => void	Pass to NexlaConnectModal.onProbeError — shows warning toast

---

Styled Components

NexlaConnectButton

Button that opens a credential modal for a specific connector. Automatically displays the connector's logo and name.

Prop	Type	Description
connector	string	Connector key (required)
onBeforeConnect	() => boolean | void	Return false to cancel
disabled	boolean	Disables the button
children	React.ReactNode	Custom label (default: "Connect {display_name}")

Also accepts all standard <button> HTML attributes except onClick.

NexlaConnectModal

Credential creation and edit dialog. Detects existing credentials automatically and switches to edit/update mode.

Prop	Type	Description
open	boolean	Controls dialog visibility
connector	string	Connector key
onClose	() => void	Called when the dialog is dismissed. Not called during active OAuth or when an authorized payload is pending save.
onSuccess	(credential: Credential) => void	Called after credential creation or update
onProbeError	(credential: Credential, message: string | null) => void	Called if the post-connect probe returns isValid: false

NexlaConnectorCard

Card component for displaying a connector in a grid or list layout. Auto-detects connected state from the credential list.

Prop	Type	Default	Description
connector	Connector	—	Connector object (required)
isConnected	boolean	Auto-detected	Override connected state display
isComingSoon	boolean	false	Disables the card and reduces opacity
viewMode	'grid' | 'list'	'grid'	Layout style
onClick	(connector: Connector) => void	—	Click handler

NexlaSnackbar

Toast notification component built on Radix UI Toast.

Prop	Type	Default	Description
open	boolean	—	Controls visibility
type	'success' | 'error' | 'warning'	'success'	Toast style
message	string	—	Content
onClose	() => void	—	Dismiss handler
autoHideDuration	number	5000	Auto-dismiss delay in ms. Set to 0 to disable.

---

Types

Credential

interface Credential {
  id: number;
  name: string;
  description: string | null;
  owner: { id: number; full_name: string; email: string } | number;
  org: { id: number; name: string } | number;
  credentials_type: string;
  credentials_version: string;
  managed?: boolean;
  connector: {
    id: number;
    type: string;
    connection_type: string;
    name: string;
    description: string;
    nexset_api_compatible: boolean;
  };
  access_roles: string[];
  verified_status: string | null;
  verified_at: string | null;
  created_at: string;
  updated_at: string;
  copied_from_id: number | null;
  vendor?: {
    id: number;
    name: string;
    display_name: string;
    connection_type: string;
    connector_id: number;
    connector_name: string;
    auth_templates: AuthTemplate[];
  };
  tags?: string[];
  credentials_non_secure_data?: Record<string, unknown>;
  template_config?: Record<string, unknown>;
}

Connector

interface Connector {
  id: number;
  name: string;
  display_name: string;
  connection_type: string;
  description: string;
  logo: string;
  small_logo: string;
  nexset_api_compatible: boolean;
  auth_templates: AuthTemplate[];
  config: ConnectorConfig;
}

AuthTemplate

interface AuthTemplate {
  id: number;
  name: string;
  display_name?: string;
  description: string;
  credentials_type?: string;
  config?: Record<string, unknown>;
  auth_parameters?: (number | ConnectorAuthParameter)[];
}

ConnectorAuthField

interface ConnectorAuthField {
  name: string;
  display_name: string;
  type: string;            // 'string' | 'password' | 'select' | 'boolean' | ...
  required?: boolean;
  default?: unknown;
  description?: string;
  placeholder?: string;
  values?: { label: string; value: string }[];  // Options for select fields
  group?: string;          // Groups fields under collapsible sections
  isHiddenField?: boolean; // Internal fields — never render
  dependsOn?: unknown;     // Conditional visibility — SDK evaluates automatically
}

NexlaConnectError

class NexlaConnectError extends Error {
  readonly code: string;       // SCREAMING_SNAKE_CASE error code
  readonly connector?: string; // Set if error occurred during connect()
}

Error codes: POPUP_BLOCKED, OAUTH_CANCELLED, OAUTH_TIMEOUT, OAUTH_ERROR, MISSING_PROVIDER, API_ERROR, RATE_LIMITED, REQUEST_TIMEOUT, APPLICATION_MISMATCH, CONNECTOR_NOT_FOUND. See Troubleshooting for resolution guidance.

NexlaConnectConfig

Read-only provider config snapshot, accessible via useNexlaConnect().config.

interface NexlaConnectConfig {
  apiBaseUrl: string;
  connectors: string[];
  applicationId: string;
  endUserId: string;
  theme?: ThemeConfig;
  locale?: string;
}

ThemeConfig

interface ThemeConfig {
  mode?: 'light' | 'dark';
  primaryColor?: string;  // CSS color string
}

---

Theme Utilities

CSS Variables

NexlaThemeProvider injects CSS variables you can use in your own styles:

Variable	Description
--nx-primary	Brand color (default: #5B4CF5)
--nx-bg	Page background
--nx-surface	Card / modal background
--nx-border	Border color
--nx-text	Primary text
--nx-text-secondary	Secondary text
--nx-error	Error red
--nx-success-bg	Success green background

getNexlaTheme(mode)

Returns a typed JS object of theme values for inline styles.

import { getNexlaTheme } from '@nexla/react-sdk';

const theme = getNexlaTheme('light');
// theme.textPrimary, theme.border, theme.primary, theme.bg, ...

nexlaTheme / nexlaDarkTheme

CSS variable maps for light and dark modes:

import { nexlaTheme, nexlaDarkTheme } from '@nexla/react-sdk';
// Record<string, string> — CSS variable name → value