@connect-xyz/auth-js

A JavaScript SDK that enables frontend applications to seamlessly integrate with the Connect Auth product.

Connect Auth provides a secure, customizable authentication flow for crypto deposits. Learn more in the Connect Auth documentation.

Installation

Via NPM (recommended)

npm install @connect-xyz/auth-js

import { Auth } from '@connect-xyz/auth-js';

Via CDN

You can import the script in your index file and use the Auth class provided by it.

<script
  type="module"
  src="https://sdk.connect.xyz/auth-web/index.js"
></script>

Or you can directly import in your javascript code.

import { Auth } from 'https://sdk.connect.xyz/auth-web/index.js';

Getting Started

Follow these simple steps to integrate Connect Auth into your frontend application:

1. Import the Auth module

import { Auth } from '@connect-xyz/auth-js';

1.1 Or import via CDN

import { Auth } from 'https://sdk.connect.xyz/auth-web/index.js';

2. Initialize the Auth module into Your App

// Create an Auth instance with configuration
const auth = new Auth({
  jwt: 'your-jwt-token',
  env: 'production', // or 'sandbox'
  theme: 'auto', // 'auto' (default), 'light', or 'dark'
  onError: ({ errorCode, reason }) => {
    console.error('Auth error:', errorCode, 'Reason:', reason);
  },
  onClose: () => {
    console.log('Auth widget closed');
  },
  onDeposit: ({ data }) => {
    console.log('Deposit completed:', data);
  },
  onEvent: ({ type, data }) => {
    console.log('Event received:', type, data);
  },
  onLoaded: () => {
    console.log('Auth widget loaded and ready');
  },
});

// Render the widget to a container element
const container = document.getElementById('auth-container');
await auth.render(container);

// Update configuration dynamically
auth.updateConfig({
  jwt: 'new-jwt-token',
  onError: newErrorHandler,
});

// Check if rendered
if (auth.isRendered()) {
  console.log('Widget is active');
}

// Clean up when done
auth.destroy();

2.1 Using Typescript (optional)

import { Auth, AuthConfig } from '@connect-xyz/auth-js';

const config: AuthConfig = {
  jwt: 'your-jwt-token',
  env: 'sandbox',
  theme: 'dark', // 'auto' (default), 'light', or 'dark'
  onError: ({ errorCode, reason }) => {
    // Handle error with type safety
  },
  onDeposit: ({ data }) => {
    // Handle deposit with type safety
  },
};

const auth = new Auth(config);

API Reference

Auth widget Props

| Prop | Type | Required | Default | Description | | ----------- | --------------------------------- | -------- | -------------- | ---------------------------------------------- | | jwt | string | Yes | - | JWT token for authentication with Connect Auth | | env | "production" \| "sandbox" | No | "production" | Target environment | | theme | "auto" \| "light" \| "dark" | No | "auto" | Theme mode for the interface | | onError | ({ errorCode, reason }) => void | No | - | Callback for error events | | onClose | () => void | No | - | Callback when the widget is closed | | onDeposit | ({ data }) => void | No | - | Callback for deposit received | | onEvent | ({ type, data }) => void | No | - | Callback for general events | | onLoaded | () => void | No | - | Callback when the widget is loaded and ready |

Constructor

new Auth(config: AuthConfig)

Creates a new Auth instance with the provided configuration.

Parameters

• config (AuthConfig): Configuration object
  • jwt (string, required): JWT token for authentication
  • env (string, optional): Environment - 'production' (default) or 'sandbox'
  • theme (string, optional): Theme mode - 'auto' (default), 'light', or 'dark'
  • onError (function, optional): Error callback
  • onClose (function, optional): Close callback
  • onDeposit (function, optional): Deposit callback
  • onEvent (function, optional): General event callback
  • onLoaded (function, optional): Callback when widget is loaded and ready

Methods

render(container: HTMLElement): Promise<void>

Renders the Auth widget to the specified container element.

await auth.render(document.getElementById('auth-container'));

updateConfig(config: Partial<AuthConfig>): void

Updates the configuration of an already rendered widget.

auth.updateConfig({
  jwt: 'new-token',
  onError: newErrorHandler,
});

destroy(): void

Removes the widget from the DOM and cleans up resources.

auth.destroy();

isRendered(): boolean

Returns whether the widget is currently rendered.

if (auth.isRendered()) {
  // Widget is active
}

getConfig(): AuthConfig

Returns a copy of the current configuration.

const config = auth.getConfig();
console.log('Current JWT:', config.jwt);

Callback Functions

For detailed information about callback events and their payloads, see the Auth SDK Callbacks documentation.

onError

Called when an error occurs in the Auth widget.

onError: ({ errorCode, reason }) => {
  // errorCode: Error code
  // reason: Human-readable error description
};

onClose

Called when the Auth widget is closed by the user.

onClose: () => {
  // Handle close event
};

onDeposit

Called when a deposit is received.

onDeposit: ({ data }) => {
  // data: Object containing deposit details
};

onEvent

Called for general events from the Auth widget.

onEvent: ({ type, data }) => {
  // type: Event type string
  // data: Event-specific data object
};

onLoaded

Called when the Auth widget has fully loaded and is ready for user interaction. This callback is useful for showing loading states or performing actions once the widget is initialized.

onLoaded: () => {
  // Widget is fully loaded and ready
};

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• All modern browsers with Web Components support

More Information & Support

For comprehensive documentation or support about Connect Auth, visit our Documentation Page.