Advanced Setup

Optional advanced configuration options for Velt SDK

Explore optional advanced configuration options to enhance your Velt implementation with locations, contacts, and initialization state detection.

Locations

Users logged into the same Document ID can see each other’s Presence, Cursors, Comments etc.

However, if you want to add another layer of categorization to organize users together, you can use Location.

If a Document is like a house, a Location is like a room within the house.

To learn more about Locations, check out its dedicated section here.

Contacts

When you reply to a comment, you can @mention other teammates that are added to a User's Contacts List.

To learn more about creating a User's Contacts List, read here.

JWT Authentication Tokens

For enhanced security, you can use JWT tokens to authenticate users instead of passing user data directly in the client-side code. This provides an additional layer of security by verifying user identity on the server side. To learn more, see the JWT Tokens page.

Access control roles (Editor/Viewer): You can assign a user’s role per resource (organization, folder, document) in the token permissions or via backend access APIs. Editors can create/edit collaboration data (e.g., comments); Viewers are read-only. See Access Control, Generate Token, Add Permissions, and Add/Update Users.

Critical JWT Token Requirements:

• JWT tokens must be generated server-side using your auth token from the Velt Console
• Never expose JWT tokens or auth tokens in client-side code
• Tokens expire after 48 hours and need to be refreshed
• Include the JWT token in the authToken field when calling identify()

Step 1: Enable JWT Tokens in Console

First, enable JWT tokens in your Velt Console:

1. Go to console.velt.dev
2. Enable the toggle for Require JWT Token (listed at the bottom of the page)

JWT tokens won’t work unless you enable this setting in your console.

Step 2: Generate Auth Token

You need an auth token to generate JWT tokens. You can generate this from the Auth Token section in your Velt Console dashboard.

Store auth tokens securely on your server-side environment and never expose them in client-side code.

Auth tokens are long-lived and should be rotated periodically for security best practices.

Step 3: Create Server Endpoint for JWT Token Generation

Create a server endpoint that generates and serves JWT tokens to your client.

See our generate_token API call for more information.

Node.js Server Endpoint

const express = require('express');
const app = express();
const PORT = 8080;

// Your credentials from Velt Console
const VELT_API_KEY = "YOUR_VELT_API_KEY";
const VELT_AUTH_TOKEN = "your-generated-auth-token-from-console";

async function generateVeltJWTToken(userId, config = {}) {
  const url = "https://api.velt.dev/v2/auth/generate_token";

  const body = {
    userId: userId,
    userProperties: {
      name: config.name,
      email: config.email,
      isAdmin: config.isAdmin || false
    },
    permissions: config.organizationId
      ? {
          resources: [
            { type: "organization", id: config.organizationId }
          ]
        }
      : undefined
  };

  try {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-velt-api-key": VELT_API_KEY,
        "x-velt-auth-token": VELT_AUTH_TOKEN
      },
      body: JSON.stringify(body),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    return data?.result?.data?.token;
  } catch (error) {
    console.error("Error generating JWT token:", error);
    throw error;
  }
}

// Endpoint to generate JWT tokens
app.get('/generate-velt-jwt-token', async (req, res) => {
  try {
    const { userId, organizationId, name, email, isAdmin } = req.query;
    const token = await generateVeltJWTToken(userId, {
      organizationId,
      name,
      email,
      isAdmin: isAdmin === 'true'
    });
    res.json({ token });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate token' });
  }
});

app.listen(PORT, () => {
  console.log(`JWT Server listening on port ${PORT}`);
});

Token Refresh

JWT tokens expire after 48 hours from generation. Handle token expiration by subscribing to the error event and refreshing tokens when needed:

If you configured an Auth Provider on VeltProvider, token refresh is handled automatically. If you authenticate using the identify() method instead, you must listen for token_expired and re-authenticate with a fresh token as shown below.

React Token Refresh

import { useVeltEventCallback } from "@veltdev/react";

export default function AuthComponent() {
  const errorEvent = useVeltEventCallback('error');

  useEffect(() => {
    if (errorEvent?.code === "token_expired") {
      // Generate new JWT token from your server
      fetch("/api/auth/refresh-token")
        .then(res => res.json())
        .then(data => {
          // Re-authenticate with new token
          useIdentify(user, { authToken: data.newToken });
        });
    }
  }, [errorEvent]);

  return <div>Authentication Component</div>;
}

Security Benefits of JWT Tokens:

• Server-side validation of user identity
• Protection against client-side data manipulation
• Secure user authentication without exposing sensitive data
• Token expiration for enhanced security

Velt Client

Access the core Velt client instance to call SDK APIs and subscribe to core events.

• API reference →

Event Subscriptions

Event	Description	Event Object
initUpdate	Initialization lifecycle updates (documents/locations set/unset, user init)	InitUpdateEvent
userUpdate	Fired when the Velt user changes (login, logout, or update)	UserUpdateEvent
documentInit	Document initialization status changes	DocumentInitEvent
error	Error events (e.g., token_expired)	ErrorEvent
veltButtonClick	Fired when a Velt Button is clicked	VeltButtonClickEvent

React / Next.js

import { useEffect } from 'react';
import { useVeltClient } from '@veltdev/react';

export default function CoreEventsListener() {
  const { client } = useVeltClient();

  useEffect(() => {
    if (!client) return;

    // Listen to initialization updates
    const initSub = client.on('initUpdate').subscribe((event) => {
      console.log('Init update:', event);
    });

    // Listen to token lifecycle errors (e.g., token_expired)
    const errorSub = client.on('error').subscribe((error) => {
      console.log('Velt error:', error);
    });

    return () => {
      initSub?.unsubscribe();
      errorSub?.unsubscribe();
    };
  }, [client]);

  return null;
}

• Use the React hook useVeltClient() inside components rendered under VeltProvider.
• The client is available after initialization. In HTML/vanilla, call Velt.init() first.
• Always unsubscribe from event subscriptions to avoid memory leaks.

getVeltInitState()

This returns true when both the Velt User and Document are initialized.

React

React / Next.js with Hooks

import { useVeltInitState } from '@veltdev/react';

export default function MyComponent() {
  const veltInitState = useVeltInitState();

  useEffect(() => {
    console.log('Velt Init State:', veltInitState);
    if (veltInitState) {
      // Velt state is initialized, so user can perform any action here
    }
  }, [veltInitState]);

  return (
    <div>
      {/* Your component content */}
    </div>
  );
}

fetchDebugInfo()

• Use this method to retrieve a one-time snapshot of essential debugging information about your Velt integration. This includes details like SDK version, API key, user, organizationId, documentId, folderId, version, and locations.
• You can also access this diagnostic information through Velt’s Chrome DevTools extension.
• Params: None
• Returns: Promise<VeltDebugInfo>

React / Next.js

const { client } = useVeltClient();

const handleFetchDebugInfo = async () => {
  const debugInfo = await client.fetchDebugInfo();
  console.log('Debug Info:', debugInfo);
  console.log('SDK Version:', debugInfo.veltVersion);
  console.log('API Key:', debugInfo.apiKey);
  console.log('Server State:', debugInfo.serverMap);
  console.log('Client State:', debugInfo.clientMap);
};

getDebugInfo()

• Use this method to subscribe to real-time updates of debugging information about your Velt integration. This includes details like SDK version, API key, user, organizationId, documentId, folderId, version, and locations.
• You can also access this diagnostic information through Velt’s Chrome DevTools extension.
• Params: None
• Returns: Observable<VeltDebugInfo>

React / Next.js

const { client } = useVeltClient();
const [debugInfo, setDebugInfo] = useState(null);

useEffect(() => {
  if (!client) return;

  const subscription = client.getDebugInfo().subscribe((info) => {
    setDebugInfo(info);
    console.log('Debug Info Updated:', info);
  });

  return () => subscription.unsubscribe();
}, [client]);