Authenticate users with Connect

This guide demonstrates how to connect to users' wallets and authenticate using Stacks.js packages.

Authentication is a fundamental part of many web applications, ensuring that users are who they claim to be and that their data is secure. With the Stacks blockchain, user authentication involves connecting to users' wallets and managing their sessions securely.

The @stacks/connect package from Stacks.js provides the tools needed to integrate this functionality seamlessly into your web app.

In this guide, you will learn how to:

  1. Install and set up the @stacks/connect package
  2. Initiate a userSession with specific permission scopes
  3. Trigger the authentication flow with the showConnect function
  4. Handle pending authentication states and manage user data

The examples in this guide are designed to be minimalistic, allowing you to easily adapt and customize them to fit your application's specific needs.

Example Repo
To see this guide in action, check out a full example here.

Install and set up the @stacks/connect package

First, install the @stacks/connect package in your project.

npm install @stacks/connect

Initiate a userSession with specific permission scopes

After installing the @stacks/connect package, initiate a userSession with the following permission scopes.

import { AppConfig, UserSession } from '@stacks/connect';

const appConfig = new AppConfig(['store_write', 'publish_data']);
const userSession = new UserSession({ appConfig });
ScopeDefinition
store_writeRead and write data to the user's Gaia hub in an app-specific storage bucket.
publish_dataPublish data so other users of the app can discover and interact with the user.
Note
We recommend you initiate the userSession object just once in your app then reference it using imports where needed.

Trigger the authentication flow with the showConnect function

Create an authenticate function that will call showConnect, triggering the popup that initiates the authentication process for users. They will authenticate with a Secret Key that's used to encrypt their private data.

function authenticate() {
  showConnect({
    appDetails: {
      name: 'My App',
      icon: window.location.origin + '/my-app-logo.svg',
    },
    redirectTo: '/',
    onFinish: () => {
      let userData = userSession.loadUserData();
    },
    userSession,
  });
}

Handle Pending Authentication

After initiating the authentication process, you will most likely need to handle cases where the user hasn't completed the authentication flow.

  1. Check if there is a pending sign-in using the isSignInPending method of the userSession object.
  2. If there is a pending sign-in, handle it by calling handlePendingSignIn which processes the sign-in and then utilizes the userData returned in a promise.
import { AppConfig, UserSession, showConnect } from '@stacks/connect';

const appConfig = new AppConfig(['store_write', 'publish_data']);
const userSession = new UserSession({ appConfig });

window.onload = function () {
  if (userSession.isSignInPending()) {
    userSession.handlePendingSignIn().then(userData => {
      // Save or otherwise utilize userData post-authentication
    });
  } else if (userSession.isUserSignedIn()) {
    // Handle case in which user is already authenticated
  }
};

For users already signed in, you can directly access their session information and proceed with your app's flow.

Note
Implementing handlePendingSignIn is particularly important in mobile app contexts to ensure a smooth user experience across all device types.

Next steps

Last updated on