Advanced Setup

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.

After authentication, retrieve the current user object anytime using getCurrentUser() or useCurrentUser().

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:

Go to console.velt.dev
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.

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.

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
Other Frameworks

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;
}

async function loadVelt() {
  await Velt.init('YOUR_VELT_API_KEY');

  const initSub = Velt.on('initUpdate').subscribe((event) => {
    console.log('Init update:', event);
  });

  const errorSub = Velt.on('error').subscribe((error) => {
    console.log('Velt error:', error);
  });

  // When done, unsubscribe
  // initSub?.unsubscribe();
  // errorSub?.unsubscribe();
}

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
Angular
Vue.js
HTML

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>
  );
}

import { Component, OnInit, OnDestroy } from '@angular/core';
import { initVelt } from '@veltdev/client';

@Component({
  selector: 'app-root',
  template: `<div><!-- Your app content --></div>`
})
export class AppComponent implements OnInit, OnDestroy {
  client: any;
  subscription: any;

  async ngOnInit() {
    this.client = await initVelt('YOUR_VELT_API_KEY');

    this.subscription = this.client.getVeltInitState().subscribe((veltInitState: boolean | undefined) => {
      console.log('Velt Init State:', veltInitState);
    });
  }

  ngOnDestroy() {
    this.subscription?.unsubscribe();
  }
}

import { initVelt } from '@veltdev/client';

export default {
  name: 'App',
  data() {
    return {
      client: null,
      subscription: null
    }
  },
  async mounted() {
    this.client = await initVelt('YOUR_VELT_API_KEY');

    this.subscription = this.client.getVeltInitState().subscribe((veltInitState: boolean | undefined) => {
      console.log('Velt Init State:', veltInitState);
    });
  },
  beforeUnmount() {
    this.subscription?.unsubscribe();
  }
}

// Subscribe to initialization state
let subscription = Velt.getVeltInitState().subscribe((veltInitState: boolean | undefined) => {
  console.log('Velt Init State:', veltInitState);
});

// To unsubscribe
subscription?.unsubscribe();

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
Other Frameworks

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);
};

const debugInfo = await Velt.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
Other Frameworks

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]);

const subscription = Velt.getDebugInfo().subscribe((debugInfo) => {
  console.log('Debug Info Updated:', 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);
});

// Unsubscribe when done
subscription.unsubscribe();

Get Started

Key Concepts

Async Collaboration

Realtime Collaboration

Self-Host Data

Model Context Protocol

Webhooks

Security

Miscellaneous

Advanced Setup

Locations

Contacts

JWT Authentication Tokens

Step 1: Enable JWT Tokens in Console

Step 2: Generate Auth Token

Step 3: Create Server Endpoint for JWT Token Generation

Token Refresh

Velt Client

Event Subscriptions

getVeltInitState()

fetchDebugInfo()

getDebugInfo()

Get Started

Key Concepts

Async Collaboration

Realtime Collaboration

Self-Host Data

Model Context Protocol

Webhooks

Security

Miscellaneous

​Locations

​Contacts

​JWT Authentication Tokens

​Step 1: Enable JWT Tokens in Console

​Step 2: Generate Auth Token

​Step 3: Create Server Endpoint for JWT Token Generation

​Token Refresh

​Velt Client

​Event Subscriptions

​getVeltInitState()

​fetchDebugInfo()

​getDebugInfo()

Locations

Contacts

JWT Authentication Tokens

Step 1: Enable JWT Tokens in Console

Step 2: Generate Auth Token

Step 3: Create Server Endpoint for JWT Token Generation

Token Refresh

Velt Client

Event Subscriptions

getVeltInitState()

fetchDebugInfo()

getDebugInfo()