Skip to main content
The Vincent Web App Client enables secure user authentication and delegation management for executing Vincent Abilities on their behalf. Using the Web App Client, you can direct users to the Vincent Connect Page where:
  • New users can review the Abilities your App is requesting and configure Vincent Policies
  • Returning users can log in and confirm their identity and authorized App Version

​
Authentication Flow

1

Redirect to Connect Page

Your App redirects users to the Vincent Connect Page
2

User Reviews and Configures

Users review requested Abilities and configure Policies
3

Return with JWT

Upon approval, users return to your App with a signed JWT
4

Verify and Store

Your App verifies and stores the JWT for authenticated requests

​
Vincent JWT

The JWT proves user authentication via their Vincent Wallet and grants your App permission to act on their behalf.

​
JWT Structure

​
header
object
Standard JWT header containing algorithm and type information
​
signature
string
Signature from User’s Vincent Wallet proving the JWT was signed using their wallet
​
data
string
The raw, unsigned payload string used during signing
To access these claims, use decodeVincentJWTFromUri in your frontend.

​
JWT Contains

​
JWT
object
The Vincent JWT containing authentication and authorization details.

​
Setting Up the Web App Client

​
getWebAuthClient
function
Creates a Vincent Web App Client instance
import { getWebAuthClient } from '@lit-protocol/vincent-app-sdk/webAuthClient';

const vincentAppClient = getWebAuthClient({
  appId: process.env.MY_VINCENT_APP_ID
});

​
Handling Authentication

​
vincentAppClient.uriContainsVincentJWT
method
Checks if the current URL contains a Vincent JWT
​
vincentAppClient.decodeVincentJWTFromUri
method
Extracts and validates JWT from URL
​
vincentAppClient.removeVincentJWTFromURI
method
Removes the Vincent JWT query parameter from the current URL
​
vincentAppClient.redirectToConnectPage
method
Redirects user to Vincent Connect Page for authentication
​
isExpired
function
Checks if a JWT has expired
import { getWebAuthClient } from '@lit-protocol/vincent-app-sdk/webAuthClient';
import { isExpired } from '@lit-protocol/vincent-app-sdk/jwt';

const vincentAppClient = getWebAuthClient({
  appId: process.env.MY_VINCENT_APP_ID
});

// Check for JWT in URL after Connect flow
if (vincentAppClient.uriContainsVincentJWT()) {
  const { decodedJWT, jwtStr } = vincentAppClient.decodeVincentJWTFromUri(
    window.location.origin
  );

  // Store JWT
  localStorage.setItem('VINCENT_AUTH_JWT', jwtStr);

  // Clean URL
  vincentAppClient.removeVincentJWTFromURI();
} else {
  // Check for existing JWT
  const storedJwt = localStorage.getItem('VINCENT_AUTH_JWT');
  const expired = storedJwt ? isExpired(storedJwt) : true;

  if (!storedJwt || expired) {
    // Redirect to Connect Page
    vincentAppClient.redirectToConnectPage({
      redirectUri: window.location.href
    });
  }
}
The redirectUri must be one of your configured Authorized Redirect URIs.

​
Backend Verification

Always verify JWTs submitted to your backend:
​
verify
function
Verifies a Vincent JWT on your backend
import { verify } from '@lit-protocol/vincent-app-sdk/jwt';

const vincentJwt = '...'; // JWT from frontend
const jwtAudience = 'https://my-redirect-uri.com';

try {
  const decodedJWT = verify(vincentJwt, jwtAudience);
  // JWT is valid and was created specifically for your App
} catch (error) {
  // JWT is invalid, expired, or mis-scoped
}
The verify method will throw an error if the JWT is invalid, expired, or mis-scoped.

​
FAQ

When a JWT expires, you’ll need to redirect the user back to the Vincent Connect Page using redirectToConnectPage(). Returning users will be able to quickly re-authenticate and get a new JWT without reconfiguring their Policies.
No, JWTs are scoped to specific redirect URIs for security. Each domain needs its own JWT obtained through the Vincent Connect flow with that domain as the redirect URI.
JWT expiration is set by the Vincent platform. Check the exp claim in the JWT to see when it expires (timestamp in seconds since Unix epoch).
The decodeVincentJWTFromUri method automatically validates JWTs in your frontend. However, you MUST always verify JWTs on your backend using the verify function before processing authenticated requests.
New users will see your App’s requested Abilities and can configure Policies before granting permission. Returning users who have already authorized your App will simply confirm their identity and the App version they’ve authorized.
Yes. If access is revoked, the user will need to repermit the app before they can generate a new JWT for it. Execution of Vincent Abilities on their behalf will also fail.
⌘I