Quick Start
Already using Auth?
Auth SDK v1.0.2 -> v1.0.3: Simply upgrade your installation to the latest Auth SDK v1.0.3 and you are good to go!
Auth SDK v0.2.2, v0.3.0 -> v1.0.3: Note that there may be breaking changes that require you to reconfigure your app and also update the integration code. For more information, see Migration Guides and Release Notes.
In this guide, you will learn how you can quickly integrate your application with the Arcana Auth SDK to:
- onboard users easily by configuring one or more authentication mechanisms.
- use Arcana wallet to sign blockchain transactions, manage tokens, and more.
Overview
To integrate an application with the Auth SDK, developers must:
- Use the Arcana Developer Dashboard to register their application and obtain a unique Client ID.
- Configure user onboarding settings for the application using the dashboard. Application users will only see the onboarding options that are configured by the developer.
- Install and integrate the application with the Auth SDK.
To enable the embedded Arcana wallet in an application, the application developers need to integrate with the Auth SDK and use the AuthProvider
interface. The AuthProvider
is a standard Ethereum Web3 provider that allows application users to sign blockchain transactions after they have been authenticated. For more information on AuthProvider
, see Auth SDK Usage Guide and Auth SDK Reference Guide.
AuthProvider
Wrappers
The AuthProvider
can be used to access the standard Ethereum provider exposed by the Auth SDK. See Auth SDK Usage Guide for details.
For easily integrating the Arcana Auth with Web3 React Apps or with those that use wallet connectors such as Wagmi and RainbowKit, Arcana also provides Auth wrappers via auth-react
and auth-wagmi
libraries.
To integrate the Auth SDK with a React App, it is recommended that you install and use the auth
as well as the auth-react
packages. For details, see React App Integration Example.
To integrate the Auth SDK with apps that use Wagmi or RainbowKit, use the ArcanaConnector
wrapper by installing and integrating with the auth-wagmi
package. You do not need to use the auth package or instantiate and initialize the AuthProvider
when using the auth-wagmi
package. For details, see Wagmi example and RainbowKit Example.
Register & Configure
First, register and configure your application using the Arcana dashboard. As part of registration, a unique value, Client ID, is assigned to each application. This is required for integrating the application with the Auth SDK.
Developers must choose one or more options to onboard users and configure social providers. This ensures that only the configured onboarding options are enabled in the Auth SDK.
Enable multiple login options
Web3 application developers can configure one or more authentication mechanisms using the dashboard and allow users to pick one of the available options to log in.
User Onboarding options
If the application is registered but none of the available social providers are enabled and configured for user onboarding, then by default, the passwordless login is the only option that is available for onboarding app users.
Install Auth SDK
npm
npm install --save @arcana/auth
yarn
yarn add @arcana/auth
CDN
<script src="https://cdn.jsdelivr.net/npm/@arcana/auth"></script>
<script src="https://unpkg.com/@arcana/auth"></script>
Integrate Application
Follow these instructions to integrate your application with the Arcana Auth SDK.
AuthProvider
Once you have installed and integrated your application, you can use the standard Ethereum Web3 Provider, AuthProvider
in your application and call SDK functions for onboarding users and signing blockchain transactions. See how to enable and use Arcana wallet for more details.
Onboard Users
After installing and integrating with the Auth SDK, application developers can add code to onboard users. Two options are available depending on how much customization is needed for your use case.
-
Use the plug-and-play feature to quickly enable the default pop-up user login interface. Developers are not required to build any user login UI. Application users can choose one of the authentication mechanisms configured by developers when the plug-and-play default UI offered by the Auth SDK shows up in the context of the application.
-
Build a custom UI for your application and call Auth SDK functions for enabling social authentication and the passwordless login option for the application users.
Sign Blockchain Transactions
Use the AuthProvider
in your application and call standard JSON RPC Web3 wallet functions programmatically. Manage user experience for signing blockchain transactions with wallet visibility settings. Enable authenticated users to sign blockchain transactions, send and receive tokens, NFTs and more using the Arcana Web3 wallet.
Deploy App
Once you have registered, configured your app via the Arcana Developer Dashboard and integrated the App with the Auth SDK, added all the required business logic to onboard users, and allow authenticated users to sign the blockchain transactions, you are ready to deploy your app.
Developers can choose to deploy one instance of the app (say, under active development) on the Arcana Testnet while simultaneously deploying a stable version of their app (say, one validated on Testnet and ready for users) on the Arcana Mainnet.
By default, when an app is registered, a 'Testnet' configuration profile is associated with the app, and a unique Client ID is assigned to this 'Testnet' profile. To deploy your app on the Arcana Mainnet, you need to create a corresponding 'Mainnet' configuration profile and update your Auth SDK integration code to use the new Client ID assigned to the app's 'Mainnet' configuration profile. Also, you need to specify the network
parameter in the AuthProvider
constructor as the 'mainnet'. For details on how to deploy your app on the Arcana Testnet / Mainnet, see App Deployment Guide.
Examples
Here are some examples of Auth SDK usage:
-
Check out how to integrate your application with Auth SDK and enable Web2-like familiar user onboarding via Google, passwordless login.
-
Manage Web3 user experience for signing blockchain transactions with the Arcana wallet:
- Enable authenticated users to sign blockchain transactions by setting the Arcana wallet visibility parameter while instantiating the
AuthProvider
. - Use pre-configured, supported blockchains or add other EVM-compatible networks programmatically as per your application requirements.
- Enable application users to check account balances, send or receive ERC-20, ERC-721, and ERC-1155 tokens, deploy smart contracts, interact with smart contracts, switch networks, manage NFT collections, and more.
- Enable authenticated users to sign blockchain transactions by setting the Arcana wallet visibility parameter while instantiating the
Developer & User Guides
For more details on how users interact with the Arcana wallet, see Arcana wallet User Guide.
Developers can refer to the Arcana Dashboard User Guide to learn more about how to register and configure the apps. Also, see Auth SDK Usage Guide and the Auth SDK Reference Guide for various functions offered by the Auth SDK.
Release Details
Refer to the Release Notes and see details about what's changed in the latest version.
You can also watch GitHub releases to receive notifications when a new release for Arcana Auth SDK is published.
See also
- User Authentication
- Video Tutorials
- Configuring Arcana wallet visibility modes
- Handling Auth SDK error messages
- Auth SDK Usage Guide
- Auth SDK Reference Guide