DocumentationServerSharing

Spreadsheet Sharing

Jspreadsheet Server supports spreadsheet sharing, allowing users to distribute their spreadsheets via links or embed them on websites. Access control is implemented by the developer, with authentication rules and permissions based on ownership, privacy, invitation status, or other criteria.

Sharing via Link

Developers define the authentication mechanism that manages access to shared spreadsheets. For instance, when a user accesses a spreadsheet link, the server can verify ownership or confirm the presence of a valid invitation. This allows users to view public spreadsheets or access private ones through invitation-based links.

Inviting a New User

Jspreadsheet Server includes an interface for generating invitations. The system creates a unique invitation token when adding a new user, which can be managed through the interface or via the API, if enabled.

Invitation Token

The invitation token is a unique hash appended to the spreadsheet URL, enabling the server to validate user permissions and control access based on predefined rules. For more details, refer to the authentication methods.

On the REST API the invitation code travels as a suffix of the Bearer token (Authorization: Bearer <token>,<invitation>); the server splits it off and exposes it to your authorization hooks as auth.invitation, alongside auth.token.

Token Persistence

The invitation is typically embedded within the spreadsheet document, as a hash on each entry of the users array:

{
    spreadsheet: {},
    users: [
        {
            email: 'test@test.com',
            level: 0, // 0 = read-only, 1 = editor, 2 = owner
            hash: '27aff468'
        }
    ]
}

When a request carries an invitation code, your access-control code matches it against users[].hash and grants the level defined on the matching invitation: 0 (read-only), 1 (editor) or 2 (owner). The full lookup is shown in authentication.

Managing Invited Users

The intrasheets extension registers owner-only REST routes to manage the invited users of a document:

• GET /api/<guid>/users: list the invited users.
• POST /api/<guid>/users: add or update invited users. The body carries a data field with a JSON-encoded array of user objects; every entry must include an email. Submitted users are merged with the current list, de-duplicated by email.
• DELETE /api/<guid>/users/<email>: remove the invited user with that email.

All three routes are gated by the server's isOwner hook, and the resulting setUsers operation is persisted through the user store you configure with intrasheets({ users: { get, set } }).

Public and Private Spreadsheets

Each document also carries a privacy flag. The API exposes it through POST /api/<guid>/privacy with a privacy field (1 or true for private, anything else for public); the route applies a setConfig change, which is an owner-only method in the reference wiring. In the reference access-control logic, a document whose privacy flag is unset grants editor access to any authenticated user, while a private document requires ownership or a valid invitation.

Custom Email Notifications

The persistence of invited users is delegated to the developer through the intrasheets extension configuration. The set callback receives the newly added or updated users in addition to the full merged list, which makes it the place to trigger invitation emails:

// Configure the intrasheets extension's user management (invited users per spreadsheet)
intrasheets({
    users: {
        get: async function(guid, auth) {
            // Only the owner can list invited users
            let level = await getUserLevel(guid, auth);
            if (level === 2) {
                return await adapter.getUsers(guid);
            }
        },
        set: async function(guid, data, newUsers, auth) {
            // Only the owner can change invited users
            let level = await getUserLevel(guid, auth);
            if (level === 2) {
                // New users might need to receive an invitation by email. Add that here
                return await adapter.setUsers(guid, data);
            }
        },
    },
});

The set callback receives four arguments: the document guid, the full merged users array to persist, the newUsers submitted in the current request (or null on removal), and the auth object of the caller.

Embed Spreadsheets

For public spreadsheets, Jspreadsheet Server can generate embeddable code snippets to integrate spreadsheets into a website. These snippets can be created directly within the Jspreadsheet Server application.

Sample Code

Users can generate an embeddable code snippet from the Jspreadsheet Server interface, as shown below:

<div id="spreadsheet"></div>
<script src="https://cdn.jsdelivr.net/npm/@jspreadsheet/cloudify/dist/index.min.js"></script>
<script>
// Create a Jspreadsheet Cloud spreadsheet
cloudify(document.getElementById('spreadsheet'), {
    url: 'https://yourddomain.com/api',
    guid: '1766f0e3-f898-47d8-8e34-f8efaee471ff',
    license: 'your-license',
});
</script>