​

Particle Auth for Web Applications

Among all the SDKs for Particle Auth, the Web SDK (@particle-network/authkit) is the most widely used. Thus, it offers extensive support and flexibility in driving onboarding through social logins, facilitating interaction with Particle’s Wallet-as-a-Service.

The Particle Auth SDK is the primary mechanism for configuring and using social logins. Whether you’re starting from scratch or already have an onboarding or authentication flow set up within your application, the Particle Auth Core Web SDK is a simple yet powerful integration.

​

Getting Started

To get started with the Particle Auth Web SDK, you can add @particle-network/authkit to your project using either of the two following mechanisms:

npm install @particle-network/authkit viem@2

yarn add @particle-network/authkit viem@2

​

Configuration

Configuration is primarily handled by wrapping an application with Particle Auth’s master configuration component, essential for authenticating your project and customizing the optional embedded wallet modal.

No matter which Particle Auth SDK you’re using, you must define your projectId, clientKey, and appId within this configuration object to authenticate your Particle Auth instance properly. Additionally, you can apply customizations to the wallet modal for a tailored user experience.

Below is an example of an index.tsx file from a create-react-app project. In this example, the AuthCoreContextProvider component acts as the configuration wrapper for the entire application.

import React from 'react'
import ReactDOM from 'react-dom/client'
import { AuthType } from '@particle-network/auth-core';
import { AuthCoreContextProvider, PromptSettingType } from '@particle-network/authkit';
import { mainnet } from '@particle-network/authkit/chains';
import App from './App'

import('buffer').then(({ Buffer }) => {
window.Buffer = Buffer;
});

ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(

  <React.StrictMode>
        <AuthCoreContextProvider
          options={{
            projectId: process.env.REACT_APP_PROJECT_ID!,
            clientKey: process.env.REACT_APP_CLIENT_KEY!,
            appId: process.env.REACT_APP_APP_ID!,
            chains: [mainnet],
            authTypes: [AuthType.email, AuthType.google, AuthType.twitter],
            themeType: "dark", // Login modal theme
            fiatCoin: "USD",
            language: "en",
            // optional, ERC4337
            erc4337: {
              name: "SIMPLE",
              version: "2.0.0",
            },
            // You can prompt the user to set up extra security measure upon login or other interactions
            promptSettingConfig: {
              promptPaymentPasswordSettingWhenSign: PromptSettingType.first,
              promptMasterPasswordSettingWhenLogin: PromptSettingType.first,
            },
            wallet: {
              themeType: 'dark', // Wallet modal theme
              visible: true,
              customStyle: {
                displayTokenAddresses: ["0x4d224452801ACEd8B2F0aebE155379bb5D594381"], // Display a custom token within the wallet modal
                priorityTokenAddresses: ["0x4d224452801ACEd8B2F0aebE155379bb5D594381"],
               },
            },
          }}
        >
    <App />
      </AuthCoreContextProvider>
  </React.StrictMode>
)

​

Interaction with Web3

Now that you’ve configured an instance of Particle Auth, it’s time to leverage Particle to facilitate social logins and interactions with Web3.

To begin, you’ll need to choose between the following interaction mechanisms:

1. Ethers.js.
2. viem.
3. Particle native.

They all achieve the same end goal of facilitating interaction with Web3, although they will result in a slightly different initialization process.

If you’ve chosen Particle native, no initialization of this nature is needed past configuring AuthCoreContextProvider or ParticleNetwork.

import { ethers } from "ethers";

import { useEthereum } from '@particle-network/authkit';

const { provider } = useEthereum();

const ethersProvider = new ethers.providers.Web3Provider(provider, "any");

You can now use the provider object to interact with Web3, enabling actions like fetching account balances or sending transactions.

​

Initiating Social Login

To interact with a user’s account (wallet), they must first log in using Particle Auth or Particle Connect, similar to how one would enter a password and unlock MetaMask.

You can use the connect and connected functions from the useConnect() hook to handle the connection logic:

import { useConnect } from '@particle-network/authkit';

const { connect, disconnect, connected } = useConnect();

// Handle user login
const handleLogin = async () => {
    if (!connected) {
        await connect({});
    }
};

// Logout user
const handleLogout = async () => {
    await disconnect();
};

In this example, the handleLogin function initiates the login process by displaying the login modal if the connected status is false, indicating that the user is not currently logged in.

​

Customize the Login Experience

You can set specific configurations within the connect() function to further tailor the login experience beyond frontend customizations.

The following example showcases all available configuration options:

'use client';

import { useConnect } from '@particle-network/authkit';

const { connect, disconnect, connected } = useConnect();

const useInfo = await connect({
    // socialType, if set, will skip the auth modal shown above and will instead automatically redirect to a chosen social login
    // 'email' | 'phone' | 'google' | 'apple' | 'twitter' | 'facebook' | 'microsoft' | 'linkedin' | 'github' | 'twitch' | 'discord'
    socialType: 'google',
    phone: '+1xxxxxxxx', // Optional, E.164 format
    code: 'xxxxxx', // Optional
    authorization: {
        uniq: true, // Optional: Defaults to false
        message: 'base58 string', // Signature message in hex or base58 for Solana
    },
});

​

Log in with a Specific Social Platform

You can streamline the login process by bypassing the standard login modal and directing users to log in with a specific social platform.

The following example shows how to automatically prompt users to log in with their Google account, skipping the login modal entirely:

'use client';

import { useConnect } from '@particle-network/authkit';

const { connect, disconnect, connected } = useConnect();

// Handle user login
const handleLogin = async () => {
    if (!connected) {
        await connect({
            socialType: 'google',
        });
    }
};

​

Customizing the Email Login Flow

By default, Particle Auth supports email login with an OTP (One Time Password) flow through the login modal. However, you can build a custom UI to request and validate OTPs directly, allowing for greater flexibility and control over the authentication experience.

Step 1: Request an OTP

Use the getConnectCaptcha() function from @particle-network/auth-core to send an OTP to the user’s email.

import { getConnectCaptcha } from "@particle-network/auth-core";

// Send an OTP to the email
const sendOtpRequest = async (email) => {
  const success = await getConnectCaptcha({ email });
  console.log(success ? "OTP sent successfully!" : "Failed to request OTP. Try again.");
};

Step 2: Verify OTP & Log In

Once the user receives the OTP, use the connect() function, including OTP and email within loginParams, to verify it and complete the login.

import { ConnectWithEmailParam } from "@particle-network/auth-core";

// Verify the OTP and log in
const verifyOtp = async (email, otp) => {
    const loginParams: ConnectWithEmailParam = { email, code: otp };
    await connect(loginParams);
    console.log("Login successful!");
};

​

Login with JWT

You can use your existing user base or authentication method with Particle Auth through JWT. This way, your users can still log in with their current accounts.

Before connecting, you must set your custom JWT configuration on the Dashboard.

Then, you can refer to the code below to log in using JWT.

'use client';

import { useConnect } from '@particle-network/authkit';

const { connect, disconnect, connected } = useConnect();

// connect with JWT
const userInfo = await connect({
    provider: 'jwt',
    thirdpartyCode: 'xxxxxxxxxx', // If applicable, JWT value
});

Learn more about Custom Authentication.

​

Implementation within a Telegram Miniapp

Before you start, ensure you’ve already created a Telegram Bot. Here is a comprehensive guide on how to do it.

Then, you need to create a Particle-Telegram app on Dashboard and get the config from the project information.

The following is an example of how you can connect with Telegram Miniapp.

'use client';

import { useConnect } from '@particle-network/authkit';

const { connect, disconnect, connected } = useConnect();

const userInfo = await connect({
    provider: 'telegram',
    thirdpartyCode: 'xxxxxxxxxx', // If applicable, Telegram Miniapp initData raw value
});

Learn more about this:

• Live Demo
• Source Code

​

Verify User Login Status

The useConnect() hook provides several functions to check the user’s connection status:

• connected — Returns a boolean value indicating whether the user is logged in (true) or not (false). This is useful for managing login logic.

• connectionStatus — Returns a string representing the current stage of the user’s flow:

  • loading
  • connecting
  • connected
  • disconnected

  You can use connectionStatus to manage login logic or to display relevant status information in the UI.

import { useConnect } from '@particle-network/authkit';

const { connectionStatus } = useConnect();

<h2 className="status-text">
    {/* Status changes are automatically handled*/}
    Status: {connectionStatus}
</h2>;

​

Handling User Information

Once the user is logged in, the userInfo object from the useAuthCore() hook becomes available.

For example, you can use it to display the user’s name and avatar, or access security details such as has_set_master_password.

This allows you to implement logic that prompts the user to set a master password if they haven’t already done so, thereby improving security.

The following is an example of how you can render user information taken from userInfo:

const { userInfo } = useAuthCore();

// Or
// const userInfo = await connect();

{
    userInfo && (
        <div>
            {/* 
      In this card, we display info from Particle Auth 
    */}
            <h2>Accounts info</h2>
            <div>
                <h2>Name: {userInfo.name}</h2>
                <img src={userInfo.avatar} alt="User Avatar" />
            </div>
        </div>
    );
}

​

Retrieving the Public Address

To retrieve the public address linked to a user’s account, when it’s not already obtained through the login via userInfo, you can use the following method:

import { ethers } from "ethers";

import { useEthereum } from '@particle-network/authkit';
const { provider } = useEthereum();

// Assuming Ethers is not already initialized
const ethersProvider = new ethers.BrowserProvider(
provider as Eip1193Provider,
"any"
);

const accounts = await ethersProvider.listAccounts();
const address = accounts[0].address;

// Or

const signer = await ethersProvider.getSigner();
const address = await signer.getAddress();

​

Sending Transactions

Sending transactions using Particle as the Signer/underlying wallet is also quite simple.

If you’re using Ethers.js, you’re already set —as long as a user has logged in with Particle, transactions can be sent as you would with any other wallet.

When a given transaction is sent, and a signature is needed for authentication, a standard confirmation popup (also customizable through the Particle dashboard) will appear directly within the application. Transactions can be sent through the following:

const signer = ethersProvider.getSigner();

const executeTx = async () => {
const signer = await ethersProvider.getSigner();

const tx = {
to: recipientAddress,
value: ethers.parseEther("0.01"),
data: "0x",
};

const txResponse = await signer.sendTransaction(tx);
const txReceipt = await txResponse.wait();

// You can log or handle the receipt here
console.log(txReceipt);
};

​

Data Signing

In cases where you’d like to sign either a raw string (personal) or typed data (eth_signTypedData), the process is quite straightforward.

You can accomplish this using standard libraries like Ethers or leveraging Particle’s native functionality. The examples below illustrate both approaches.

For instance, when sending transactions, the signatures are automatically formatted and presented to the user in a popup request. This ensures a user-friendly experience by displaying the relevant data in UTF-8 format.

​

Personal Signatures

const msg = 'GM, Particle!';

// After configuring AuthCoreContextProvider and logging in
const { signMessage } = useEthereum();

const result = await signMessage(msg);

​

Sign Typed Data

// Placeholder data
const msg = { ... };

// After configuring AuthCoreContextProvider and logging in
const { signTypedData } = useEthereum();

const result = await signTypedData({ data: msg, version: 'V4' });

​

Enabling Blind Signatures

To enable blind signatures (signing without a confirmation popup) in Particle Auth, certain conditions must be met when configuring the AuthCoreContextProvider component and setting up the authentication flow.

1. Master Password Requirement

   • Users must either:
     • Have entered the master password, or
     • Not have set a master password in the first place.

2. No Payment Password

   • Users should not have set a payment password (as this interrupts the signing process).

3. Disable Payment Password Prompt Setting

   • Set the promptPaymentPasswordSettingWhenSign parameter to false within AuthCoreContextProvider.

   // Configuration for disabling payment password prompt
   promptSettingConfig = {
       promptPaymentPasswordSettingWhenSign: false,
   };

When these conditions are satisfied, blind signing is enabled.

​

Particle Native Hooks

Below is a collection of examples describing the different hooks available with Particle Auth.

These hooks facilitate social login and native application-level interaction (such as message signing, sending transactions, etc.) directly through Particle Auth.

​

useConnect

useConnect acts as the primary hook for facilitating login (connection) with Particle Auth.

import { useConnect } from '@particle-network/authkit';

const { connect, disconnect, connected, connectionStatus, requestConnectCaptcha, setSocialConnectCallback } =
    useConnect();

const userInfo = await connect();

const isLoggedIn = connected;

await disconnect();

​

useEthereum

useEthereum provides direct interaction with a given EVM chain as an alternative to a traditional library such as ethers.

const {
    provider, // EIP1193 provider
    address, // EVM public address
    chainId, // Current chain
    chainInfo,
    switchChain,
    signMessage,
    signTypedData,
    sendTransaction,
    enable,
} = useEthereum();

const txHash = await sendTransaction({
    to: '0xe8fc0baE43aA264064199dd494d0f6630E692e73',
    value: '1000000',
});

const signature = await signMessage(message);

const signature = await signTypedData(typedData);

await switchChain('0x1'); // Also takes a standard number

​

useSolana

useSolana is one of the primary ways to use Solana with Particle Auth if you aren’t using an external connection modal such as wallet-adapter.

import { useSolana } from '@particle-network/authkit';

const {
    address, // Solana public address
    chainId, // Current chain (Mainnet, Testnet, Devnet)
    chainInfo,
    switchChain,
    signMessage,
    signTransaction,
    signAllTransactions,
    signAndSendTransaction,
    enable,
} = useSolana();

const txHash = await signAndSendTransaction(txData);

const signature = await signMessage(message);

​

useAuthCore

useAuthCore provides additional functionality, such as retrieving userInfo after login, forcing different account menus to open, accessing the on-ramp page, and more.

import { useAuthCore } from '@particle-network/authkit';

const {
    userInfo, // Standard user info, null is returned if not connected
    needRestoreWallet, // Whether or not a master password is needed from the current user
    openAccountAndSecurity, // Opens account and security modal
    openSetMasterPassword, // Opens set master password modal
    openChangeMasterPassword, // Opens change master password modal
    openRestoreByMasterPassword, // Opens input master password modal
    openSetPaymentPassword, // Opens set payment password modal
    openChangePaymentPassword, // Opens change payment password modal
    openSetSecurityAccount, // Opens set security account modal
    openLinkLoginAccount, // Opens link login account modal
    openWallet, // Opens wallet in iframe
    getWalletIFrame, // Manages the embedded wallet modal, used for opening the wallet modal in a custom iframe
    openBuy, // Opens the onramp aggregation page
} = useAuthCore();

​

useCustomize

useCustomize provides several methods for customizing the wallet modal, such as changing the theme type (light or dark), creating a custom style, changing the language, and more.

import { useCustomize } from '@particle-network/authkit';

const {
    setThemeType, // Sets theme type, 'light' or 'dark'
    setCustomStyle, // Sets custom modal styles
    setWalletOptions, // Sets wallet modal options
    setLanguage, // Sets language being used
    setFiatCoin, // Sets fiat coin being used
    setERC4337, // Sets whether the modal has ERC-4337 enabled
} = useCustomize();

​

External Connection Kits

Integrating and leveraging Particle Auth isn’t limited to interfaces provided by Particle Network; instead, it’s built to fit into nearly every implementation scenario. Whether you’re using RainbowKit, Web3Modal, or Solana’s wallet-adapter or would like to have a standalone social login button within your application, Particle Auth can be used.