Skip to main content

How to use the Verida Connect SDK

caution

The Verida Connect APIs are subject to change during the developer preview phase.

Initialize a connection to the Verida network using a private key stored on the user’s mobile device using the Verida Vault.

This easy to use integration method allows a user to scan a QR code to sign into your application. If the user doesn’t have the Verida Vault installed, they will be prompted to install it. Existing users will be prompted to authorize your application to access encrypted storage for that application.

Installation

This requires installing the @verida/account-web-vault dependency:

npm install  @verida/account-web-vault

Usage

Here’s how you initialize an application context:

import { Network, EnvironmentType } from '@verida/client-ts';
import { VaultAccount } from '@verida/account-web-vault';

const VERIDA_ENVIRONMENT = EnvironmentType.TESTNET;
const CONTEXT_NAME = 'My Application Context Name';

// The LOGO_URL should be a 170x170 PNG file
const LOGO_URL = "https://assets.verida.io/verida_login_request_logo_170x170.png";

const account = new VaultAccount({
request: {
logoUrl: "https://assets.verida.io/verida_login_request_logo_170x170.png",
openURL: window.location.href, // will redirect the user to this same page after accepting the login request in the Vault app
}
});

const context = Network.connect({
client: {
environment: VERIDA_ENVIRONMENT,
},
account: account,
context: {
name: CONTEXT_NAME,
},
});
if (!context) {
console.log(
'User cancelled login attempt by closing the QR code modal or an unexpected error occurred'
);
}

Configuration

Various configuration options can be set (as parameters in VaultAccount) for the Verida Connect SDK.

These (all optional) config options include:

  • serverUri? — A string representing the WSS URI
  • loginUri? — The login URI or page where the user will be sent to login using the app; ie: vault.verida.io.
  • canvasId? — A string representing the DOM id where the QR code canvas will be injected
  • request? — An object representing an authorization request that matches https://vault.schemas.verida.io/auth/loginRequest/latest/schema.json
  • request?.logoUrl? — The URL of a 170x170 PNG logo to display in the vault
  • request?.openUrl? — An optional URL for the Vault to open in the default browser on the user's mobile device after login is accepted. This will automatically authorize the user in local storage so future page loads of your application will be authenticated.
  • request?.walletConnect? — (Coming soon) An optional configuration to automatically establish a wallet connection upon sign in. Required parameters; version (Wallet connect version; 1 or 2), uri (WalletConnect bridging server), chainId (A CAIP chain ID such as eip155:1 for ethereum mainnet)
  • callback? — A callback function when the auth response is received.
  • deeplinkId? — The HTML element ID of a link that should have the deeplink URI attached to the href property

Notes

Due to limitations, the redirection of the user, enabled by the request?.openUrl? option, will open a new tab in the default browser.

It is recommended to use the hasSession method and a conditional connect() to optimise the user experience. An example of this pattern is shown in the Single Sign On tutorial.

Authorization uses an accessToken and a refreshToken. If an accessToken expires, the SDK will automatically attempt to fetch a new accessToken using the refreshToken. If the refreshToken has expired, the SDK will re-open the QR code SSO modal and ask the user to re-login before continuing. Any existing network connections will be restored once the user logs in again.