Overview

Velt organizes your collaborative data in a clear hierarchy. This structure helps control Velt feature data access with precision. The hierarchy is: Organization → Folders → Documents → Locations. Here are the core concepts:

Organizations: The top-level container for everything. Think of it as your customer’s entire account (e.g., Meta). It holds all their users, groups, and collaborative data.
Folders: A way to group and organize documents, just like in a file system. Folders can contain other folders and documents, inheriting permissions.
Documents: The primary collaborative space. This is where features like comments, presence, and cursors come alive. A document could be a design file, a dashboard, a spreadsheet, or a specific page in your app.
Locations: An optional, granular subspace within a document. If a document is a slide deck, a location is a single slide. If a document is a video, a location could be a specific timestamp.
Users: Your end users who use your app.
Access Control: The rules that control who can access what Velt feature data.
Authentication: The process of authenticating a user in Velt.

Organizations

Overview

An Organization is the top-level entity.

It contains folders, documents, locations and users.
Think of an organization as the account belonging to a company (e.g., Company A). This account may have several users (Company A employees). A document will be any file created within the organization (e.g., document, spreadsheet, slides, etc.). A location will be any child section within the document (e.g., slide within a presentation).

Properties

By default, Users within the organization can access all of it’s resources like folder, documents, contact list etc. This can be modified using access control settings.
A user can be added to multiple organizations but can only log in to one organization at a time.
Access to resources can be restricted by setting controls at the individual resource level.

APIs

Create Organization

When the user signs into an organization it will be created automatically if it doesn’t exist.
Explicitly create an organization using the REST API. Learn more

Update Organization

Update organization using the REST API. Learn more

Delete Organization

Delete organization using the REST API. Learn more
It will delete all the data (folders, documents, locations and users) within the organization.

Get Organization

Get organization and it’s metadata using the REST API. Learn more

Disable Organization

Disable CRUD access to an organization using the REST API. Learn more

Provision Access to an Organization

Provision access to an organization using access control APIs

Sign in the user into an organization using these options.
User needs to sign in to an organization in order to perform CRUD operations on it.

Folders

Overview

Folders help you organize documents in a hierarchical way, like a traditional file system.

Properties

Folders can contain both documents and subfolders.
Folders use the same permission model as Organizations and Documents.
By default, folders inherits the permission from it’s organization.
A user can be added to multiple Folders but can only initialize one Folder at a time.
By default, all Folder users have access to all Folder resources including sub folders, documents, locations and user contacts.
Access to individual resources within the Folder cannot be restricted by setting controls at the individual resource level.
Access of the Folder cascades to all resources within the Folder.

APIs

Create Folder

Create a folder using the REST API. Learn more

Update Folder

Update folder using the REST API. Learn more

Move Documents to Folder

Move documents to a folder using the REST API. Learn more

Delete Folder

Delete folder using the REST API. Learn more
It will delete all the data (subfolders, documents, locations and users) within the folder.

Get Folder

Get folder and it’s metadata using the REST API. Learn more

Update Folder Access Type

Update the access type of a folder using the REST API. Learn more

Provision Access to a Folder

Provision access to a folder using access control APIs

Subscribe to a folder and its documents using the setDocuments method.
Subscribe to all documents in the folder or a specific set of documents. If you want to subscribe to specific documents in the folder then you can pass upto 30 documents at a time.

Using Hooks:

const { setDocuments } = useSetDocuments();

{/* Subscribe to a folder and all its documents */}
const rootDocument = [
  {
    id: 'document-1',
    metadata: {
      documentName: 'Document 1'
    }
  }
];

setDocuments(
  rootDocument,
  {
    folderId: 'folder1',
    allDocuments: true
  }
);


{/* Subscribe to a folder and some documents */}
const documents = [
  {
    id: 'document-1',
    metadata: {
      documentName: 'Document 1'
    }
  },
  {
    id: 'document-2',
    metadata: {
      documentName: 'Document 2'
    }
  }
];

setDocuments(
  documents,
  {
    folderId: 'folder1',
  }
);

Using API:

{/* Subscribe to a folder and all its documents */}
await client.setDocuments(
  rootDocument,
  {
    folderId: 'folder1',
    allDocuments: true
  }
);

{/* Subscribe to a folder and some documents */}
await client.setDocuments(
  documents,
  {
    folderId: 'folder1',
  }
);

Fetch folder metadata

Retrieve folder metadata and its subfolders using either organizationId or folderId, with support for pagination.

// Get all folders for a specific organization
const folderMetadata = await client.fetchFolders({
  organizationId: 'org1'
});

// Get a specific folder's metadata with its immediate subfolders
const folderMetadata = await client.fetchFolders({
  organizationId: 'org1',
  folderId: 'folder1'
});

console.log(folderMetadata); // { data: { folder1: { ... } }, nextPageToken: '...' }

Documents

Overview

A Document is a collaborative space within an Organization where users work together in real time. Each document includes:

Feature data (such as Comments, Presence, Cursors, etc.)
Locations
Users (distinct from Organization users; see Access Control for details)

For example, in a slide presentation app, the whole slide deck would be a single document.

Properties

Anyone connected to the same documentId can see and interact with each other’s activity, like presence, cursors, comments etc.
Users can subscribe to a single document or multiple documents at the same time.
Document inherits the permission from it’s organization and parent folder.
A user can be added to multiple Documents.
You can set Document level access control to override the Organization’s access control it inherited but not the Folder’s access control.

APIs

Use this to set and subscribe to one or multiple documents at the same time.
You can specify 30 documents at a time.
The first document in the list will be considered as the root document.
For features like comments, notifications, recorder, reactions etc. you will be able to read and write to multiple documents at the same time.
For features like cursors, presence, huddle, live state sync etc. it will default to the root document.
Sidebar will automatically show data from all the documents.

Params:

documents: Document[]
options?: SetDocumentsRequestOptions

Using Hooks:

const documents = [
  {
    id: 'document-1',
    metadata: {
      documentName: 'Document 1'
    }
  },
  {
    id: 'document-2',
    metadata: {
      documentName: 'Document 2'
    }
  }
];
const { setDocuments } = useSetDocuments();
setDocuments(documents);

Using API:

const documents = [
  {
    id: 'document-1',
    metadata: {
      documentName: 'Document 1'
    }
  },
  {
    id: 'document-2',
    metadata: {
      documentName: 'Document 2'
    }
  }
];
await client.setDocuments(documents);

Read/Write data from multiple documents on the same page

If you want to display data (eg: comments) from multiple documents on the same page, add data-velt-document-id attribute to the container that contains the document.
It will be used to identify which part of the DOM belongs to which document.

<div class="document-container" data-velt-document-id="document-1">
  ...
</div>

<div class="document-container" data-velt-document-id="document-2">
  ...
</div>

<div class="document-container" data-velt-document-id="document-3">
  ...
</div>

By default, users can only access documents within their own organization.
Enable cross-organization access by specifying the organizationId of the target document in the document metadata.
Ensure that the user has access to the target document in the target organization.

Using Hook:

{/* Single Document */}
useSetDocument("DOCUMENT_ID", {
  organizationId: 'ANOTHER_ORGANIZATION_ID'
});

{/* Multiple Documents */}
const documents = [
  {
    id: 'document-1',
    metadata: {
      documentName: 'Document 1'
    }
  },
  {
    id: 'document-2',
    metadata: {
      documentName: 'Document 2'
    }
  }
];
useSetDocuments(documents, {
  organizationId: 'ANOTHER_ORGANIZATION_ID'
});

Using API:

{/* Single Document */}
await client.setDocument("DOCUMENT_ID", {
  organizationId: 'ANOTHER_ORGANIZATION_ID'
});

{/* Multiple Documents */}
const documents = [
  {
    id: 'document-1',
    metadata: {
      documentName: 'Document 1'
    }
  },
  {
    id: 'document-2',
    metadata: {
      documentName: 'Document 2'
    }
  }
];
await client.setDocuments(documents, {
  organizationId: 'ANOTHER_ORGANIZATION_ID'
});

Set Root Document

Set the root document.
This is useful when you have multiple documents subscribed in your app and you want change the root document during the session.

await client.setRootDocument({id:'DOCUMENT_ID'})

Unsubscribe from Documents

Use this to unsubscribe from all documents at once.

Using Hooks:

useUnsetDocuments();

Using API:

await client.unsetDocuments();

Get Document Metadata

Use this to get the metadata of a Document.
This is useful when you want to display the document name in your app or any custom metadata that you have set.
This returns a subscription with DocumentMetadata object.

client.getDocumentMetadata().subscribe((documentMetadata) => {
  console.log("Current document metadata: ", documentMetadata);
});

Create Document

Create a document using the REST API. Learn more

Update Document

Update document using the REST API. Learn more

Delete Document

Delete document using the REST API. Learn more
It will delete all the data (locations and users) within the document.

Get Document

Get document and it’s metadata using the REST API. Learn more

Update Document Access Type

Update the access type of a document using the REST API. Learn more

Provision Access to a Document

Provision access to a document using access control APIs

Disable Document

Disable CRUD access to a document using the REST API. Learn more

Legacy APIs

Subscribe to a Single Document

Use this to initialize and subscribe to a single Document.
Once you set the document, you will start receiving realtime updates from the document.
Params:
- documentId: The unique identifier for the document.
- metadata: (optional) This is a key/value pair object where you can set metadata about the document such as documentName. documentName is a special field that we use to display the document name in some Velt Components.

Using Hooks:

useSetDocument('unique-document-id', {documentName: 'Document Name'});

Using API:

await client.setDocument('unique-document-id', {documentName: 'Document Name'});

Unsubscribe from a Single Document

Use this to unsubscribe from the root Document
Once you unset the document, you will no longer receive realtime updates from the document.
For some parts of your app, you may not need Velt. In such cases, you can unset the document.

Using Hooks:

useUnsetDocumentId();

Using API:

await client.unsetDocumentId();

Locations

Overview

Locations are optional subspaces (JSON object) within a document, providing finer partitioning of data. Locations can represent:

Pages
Sections
Video frames
Data points on maps/charts
Any other contextual area

For instance:

In a slide presentation, the entire slide presentation will be a document each individual slide will be a location.
In a dashboard, the entire dashboard is a document but various filters applied will be locations;
In a video player, the entire video will be the document and timestamps will be locations.

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

Properties

Any user with access to the document will have access to all locations in the document.
Access controls cannot be set at the location level.
Locations automatically generate location groups in the sidebar and organizes the comments within the group.
The location object has these fields:
- id (required): A unique identifier for the location that can be used to reference it later
- locationName (recommended): A human-readable name displayed in Velt components like the VeltCommentsSideBar
- You can add any number of custom fields to the location object.

APIs

Use this to set and subscribe to one or multiple locations at the same time.
The first location in the list will be considered as the root location.
Features will by default add data to the root location unless you use the location boundaries.
Sidebar will automatically show data from all the documents.

Params:

locations: Location[]
options?: SetLocationsRequestOptions
- rootLocationId: The id of the location that will be set as the root location. If you don’t specify this, the first location will be set as the root location.
- appendLocation: If you want to append new locations to the existing locations, set this to true.

Using Hooks:

const locations = [
  {id:'location1', locationName:'Location 1'},
  {id:'location2', locationName:'Location 2'}
];
const { setLocations } = useSetLocations();
setLocations(locations);

Using API:

  await client.setLocations([
    {id:'location1', locationName:'Location 1'},
    {id:'location2', locationName:'Location 2'}
  ], {rootLocationId: 'location2'}); // By default 1st location will be set as root location unless rootLocationId is specified.

  // Append new locations
  await client.setLocations([
    {id:'location3', locationName:'Location 3'},
    {id:'location4', locationName:'Location 4'}
  ], {appendLocation: true})

Read/Write data from multiple locations on the same page using Location Boundaries

If you want to display data (eg: comments) from multiple locations on the same page, add data-velt-location-id attribute to the container that contains the location.
It will be used to identify which part of the DOM belongs to which location.
This ensures that the comment added within the location is associated with the correct location.

<div class="location-container" data-velt-location-id="location-1">
  ...
</div>

<div class="location-container" data-velt-location-id="location-2">
  ...
</div>

<div class="location-container" data-velt-location-id="location-3">
  ...
</div>

Set Root Location

Set the root location.
This is useful when you have multiple locations subscribed in your app and you want change the root location during the session.

await client.setRootLocation({id:'LOCATION_ID'})

Unsubscribe from Locations

Unset locations by ids or all of them if you don’t specify any parameters.

// remove specific locations
await client.unsetLocationsIds(['location1', 'location2', 'location3'])

// remove all locations
await client.unsetLocationsIds()

Legacy APIs

Subscribe to a Single Location

Use this to initialize and subscribe to a single Location.

Using Hooks:

useSetLocation({
  'id': 'locationId1',
  'locationName': 'MainVideoPlayer',
  'videoFrame': '120'
})

Using API:

client.setLocation({
  'id': 'locationId1',
  'locationName': 'MainVideoPlayer',
  'videoFrame': '120'
})

Subscribe to Multiple Locations

Use this to subscribe to multiple locations at the same time.
Add additional locations on the page by using set location with the true parameter.

Using Hooks:

useSetLocation({
  'id': 'locationId1',
  'locationName': 'MainVideoPlayer',
  'videoFrame': '120'
  // You can keep adding more field to make the location very specific.
  // The field names can be anything.
})

useSetLocation({
  'id': 'locationId1',
  'locationName': 'MainVideoPlayer',
  'videoFrame': '120'
  // You can keep adding more field to make the location very specific.
  // The field names can be anything.
}, true)

Using API:

client.setLocation({
  'id': 'locationId1',
  'locationName': 'MainVideoPlayer',
  'videoFrame': '120'
  // You can keep adding more field to make the location very specific.
  // The field names can be anything.
});

client.setLocation({
  'id': 'locationId2',
  'locationName': 'MainVideoPlayer2',
  'videoFrame': '120'
  // You can keep adding more field to make the location very specific.
  // The field names can be anything.
}, true);

Users

Overview

A User is anyone authenticated with the Velt SDK.
After authentication, a user’s profile appears in Velt’s collaboration features. For example, their name is shown next to their comments, in @mentions, and alongside their avatar in presence and cursor features.

Contact List

When the user is on a document, they can @mention other users. By default, the contact list for the @mention feature includes users from:

Organization.
Folder.
Document.
User Groups.
@here: This is a special group that includes only the users explicitly added on the document. This doesn’t include organization users or organization user groups.

User Groups

User Groups let you organize users into teams (like “engineering” or “marketing”) for easier management and access control.

Mention an entire group (e.g., @engineering) instead of individual users, similar to Slack.
Organization users can be in multiple groups.
Only organization users can join user groups.

Properties

Uniqueness of the user is determined by its userId.
A user can be part of multiple organizations.

APIs

There are two ways to authenticate a user in Velt.

Using an Auth Provider (recommended)
Using Identify method

1. Use Auth Provider

With this approach, you configure an authentication provider by specifying the user you want to authenticate and a function that returns a Velt JWT token.
This function is automatically called by Velt whenever a token is required—such as during the initial sign-in or when the token expires.
You should define this authentication provider within the Velt Provider during your app’s initialization.
Use this to generate a Velt JWT token.
Params:
- user: User
- retryConfig: AuthRetryConfig
- generateToken: () => Promise<string>

<VeltProvider authProvider={{
  user,
  retryConfig: { retryCount: 3, retryDelay: 1000 },
  generateToken: async () => {
    const token = await __generateVeltAuthTokenFromYourBackend__();
    return token;
  }
}} />

2. Use Identify with JWT Token

In this approach, you will call the identify method with the user object and a JWT token.
Here you are responsible for re-generating a JWT token whenever it expires.
This gives you more flexibility on when and where to initialize the user and generate the token.
Params:
- user: User
- options: Options
  - authToken: string
  - forceReset: boolean

Using Hook:

  const user = {
    userId: uid,
    organizationId: organizationId, // this is the organization id the user belongs to. You should always use this.
    name: displayName,
    email: email,
    photoUrl: photoURL,
    color: colorCode, // Use valid Hex code value. Used in the background color of the user's avatar.
    textColor: textColor // Use valid Hex code value. Used in the text color of the user's intial when photoUrl is not present.
  };

  useIdentify(user, {
    authToken: authToken, // this is optional but highly recommended.
  });

Using API:

await client.identify(user, {
    authToken: authToken, // this is optional but highly recommended.
});

Sign in with force reset

By default, when you identify a user, their authentication state is preserved in the browser until you explicitly sign them out.
If you update a user’s metadata or default access settings in the console and want those changes to take effect right away, you should call the identify method again with the forceReset option set to true.
Default: false

await client.identify(user, {
  forceReset: true
});

Sign out a User

In a given session or browser tab, if you want to switch users, you need to first signout the current user and then sign in using identify method again. This will ensure we clean up the current user session and start a new session with the new user.

client.signOutUser();

Contact List:

User Groups:

Access Control

Overview

There are two ways to manage access control of Velt features and data:

On Demand Access Control: Your app may have a very complex and granular access control system in place. Instead of mapping that into Velt, this allows you to have complete flexibility with very little setup. Instead of pre-syncing users and running a ongoing sync job, you can grant temporary time based access or permanent access to the resource. Whenever the user logs in and accesses a resource in your app, you can use our API to grant or revoke access to Velt features and data on the fly.
Synced Access Control: Use this if you have a traditional hierarchical access control system like Google Drive. This requires slightly more setup.

Initial syncing: Once you set up Velt, you can do a one time sync of your existing users in Velt.
Ongoing syncing: When a user is added or removed in your app, you will also need to add or remove them from Velt.

1. On Demand Access Control

Types

Temporary access: Access is granted for a specific time period.
Permanent access: Access is granted permanently until you explicitly revoke it.

Generate a JWT token with the user’s information and the resource id. Learn more

Frontend:

<VeltProvider authProvider={{
  user,
  retryConfig: { retryCount: 3, retryDelay: 1000 },
  generateToken: async () => {
    const token = await __generateVeltAuthTokenFromYourBackend__();
    return token;
  }
}} />

Backend: Refer to Generate Token REST API

When User switches between resources

a. Add permissions: Refer to Add Permissions REST API b. Remove permissions: Refer to Remove Permissions REST API

2. Synced Access Control

Initial syncing

You can add users in bulk using Add Users REST API When you use identify API and have auto-create organization users enabled in console, the user will be added to the organization after successful login.

Ongoing syncing

When a user is added or removed in your app, you will also need to add or remove them from Velt using the:

Access Control Types

These can be applied to Folder and Document resources.

public: default Any user who successfully initializes the given Velt resource can access the resource data whether or not they are part of the resource.
organizationPrivate: All users in the same organization as the resource can access the resource.
restricted: Only users explicitly added to the resource will have access.

Changing access control types:

Changing default: You can change the default access control using the console.
Changing access control for a specific resource:
- Folder: You can change the access control using the REST API.
- Document: You can change the access control using the REST API.

Resources on which access control can be applied

Organization
Folder
Document

Get Started

Key Concepts

Async Collaboration

Realtime Collaboration

Self-Host Data

Model Context Protocol

Webhooks

Security

Miscellaneous

​Overview

​Organizations

​Overview

​Properties

​APIs

​Create Organization

​Update Organization

​Delete Organization

​Get Organization

​Disable Organization

​Provision Access to an Organization

​Sign in User into an Organization

​Folders

​Overview

​Properties

​APIs

​Create Folder

​Update Folder

​Move Documents to Folder

​Delete Folder

​Get Folder

​Update Folder Access Type

​Provision Access to a Folder

​Subscribe to a folder

​Fetch folder metadata

​Documents

​Overview

​Properties

​APIs

​Subscribe to Documents

Read/Write data from multiple documents on the same page

​Subscribe to Documents from Other Organizations

​Set Root Document

​Unsubscribe from Documents

​Get Document Metadata

​Create Document

​Update Document

​Delete Document

​Get Document

​Update Document Access Type

​Provision Access to a Document

​Disable Document

​Legacy APIs

Subscribe to a Single Document

Unsubscribe from a Single Document

​Locations

​Overview

​Properties

​APIs

​Subscribe to Locations

Read/Write data from multiple locations on the same page using Location Boundaries

​Set Root Location

​Unsubscribe from Locations

​Legacy APIs

Subscribe to a Single Location

Subscribe to Multiple Locations

​Users

​Overview

​Contact List

​User Groups

​Properties

​APIs

​Sign in a User

1. Use Auth Provider

2. Use Identify with JWT Token

Sign in with force reset

​Sign out a User

​Contact List:

​User Groups:

​Access Control

​Overview

Overview

Organizations

Overview

Properties

APIs

Create Organization

Update Organization

Delete Organization

Get Organization

Disable Organization

Provision Access to an Organization

Sign in User into an Organization

Folders

Overview

Properties

APIs

Create Folder

Update Folder

Move Documents to Folder

Delete Folder

Get Folder

Update Folder Access Type

Provision Access to a Folder

Subscribe to a folder

Fetch folder metadata

Documents

Overview

Properties

APIs

Subscribe to Documents

Subscribe to Documents from Other Organizations

Set Root Document

Unsubscribe from Documents

Get Document Metadata

Create Document

Update Document

Delete Document

Get Document

Update Document Access Type

Provision Access to a Document

Disable Document

Legacy APIs

Locations

Overview

Properties

APIs

Subscribe to Locations

Set Root Location

Unsubscribe from Locations

Legacy APIs

Users

Overview

Contact List

User Groups

Properties

APIs

Sign in a User

Sign out a User

Contact List:

User Groups:

Access Control

Overview

1. On Demand Access Control

Types

During login

When User switches between resources

2. Synced Access Control

Initial syncing

During login

Ongoing syncing

Access Control Types

Resources on which access control can be applied