跳到主要内容

Lock and unlock a file

This example demonstrates how to lock or unlock the specified file in ONLYOFFICE DocSpace and get a list of users and their access levels for the file.

Before you start​

  1. Replace https://yourportal.onlyoffice.com and YOUR_API_KEY with your actual DocSpace portal URL and API key. Ensure you have the necessary data and permissions to perform migration operations.
  2. Before you can make requests to the API, you need to authenticate. Check out the Personal access tokens page to learn how to obtain and use access tokens.
Full example
// Set API base URL
const API_HOST = 'yourportal.onlyoffice.com';
const API_KEY = 'your_api_key';

// Headers with API key for authentication
const HEADERS = {
  Authorization: `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
};

// Step 1: Lock a file by ID
function lockFile(fileId) {
  const url = `https://${API_HOST}/api/2.0/files/file/${fileId}/lock`;
  const data = { lockFile: true };

  return fetch(url, {
    method: 'PUT',
    headers: HEADERS,
    body: JSON.stringify(data),
  })
    .then(async (res) => {
      if (res.status === 200) return res.json();
      const text = await res.text();
      console.log(`File lock failed. Status code: ${res.status}, Message: ${text}`);
      return null;
    })
    .catch((err) => {
      console.log(`File lock error: ${err.message}`);
      return null;
    });
}

// Step 2: Unlock a file by ID
function unlockFile(fileId) {
  const url = `https://${API_HOST}/api/2.0/files/file/${fileId}/lock`;
  const data = { lockFile: false };

  return fetch(url, {
    method: 'PUT',
    headers: HEADERS,
    body: JSON.stringify(data),
  })
    .then(async (res) => {
      if (res.status === 200) return res.json();
      const text = await res.text();
      console.log(`File unlock failed. Status code: ${res.status}, Message: ${text}`);
      return null;
    })
    .catch((err) => {
      console.log(`File unlock error: ${err.message}`);
      return null;
    });
}

// Step 3: View users with access to the file
function getProtectedFileUsers(fileId) {
  const url = `https://${API_HOST}/api/2.0/files/file/${fileId}/protectusers`;
  return fetch(url, {
    method: 'GET',
    headers: HEADERS,
  })
    .then(async (res) => {
      if (res.status === 200) return res.json();
      const text = await res.text();
      console.log(`Protected file users retrieval failed. Status code: ${res.status}, Message: ${text}`);
      return null;
    })
    .catch((err) => {
      console.log(`Protected file users retrieval error: ${err.message}`);
      return null;
    });
}

// Run
const file_id = '123456'; // Replace with a valid file ID

lockFile(file_id)
  .then(() => unlockFile(file_id))
  .then(() => getProtectedFileUsers(file_id));

Step 1: Lock a file​

A PUT request is sent to /api/2.0/files/file/:fileId/lock with the payload:

  • lockFile: True — Lock a file.

This prevents other users from editing the file until it is unlocked.

function lockFile(fileId) {
  const url = `https://${API_HOST}/api/2.0/files/file/${fileId}/lock`;
  const data = { lockFile: true };

  return fetch(url, {
    method: 'PUT',
    headers: HEADERS,
    body: JSON.stringify(data),
  })
    .then(async (res) => {
      if (res.status === 200) return res.json();
      const text = await res.text();
      console.log(`File lock failed. Status code: ${res.status}, Message: ${text}`);
      return null;
    })
    .catch((err) => {
      console.log(`File lock error: ${err.message}`);
      return null;
    });
}

Step 2: Unlock a file​

A PUT request is sent to the same endpoint with the payload:

  • lockFile: False — Unlock a file.

This re-enables editing for the file.

function unlockFile(fileId) {
  const url = `https://${API_HOST}/api/2.0/files/file/${fileId}/lock`;
  const data = { lockFile: false };

  return fetch(url, {
    method: 'PUT',
    headers: HEADERS,
    body: JSON.stringify(data),
  })
    .then(async (res) => {
      if (res.status === 200) return res.json();
      const text = await res.text();
      console.log(`File unlock failed. Status code: ${res.status}, Message: ${text}`);
      return null;
    })
    .catch((err) => {
      console.log(`File unlock error: ${err.message}`);
      return null;
    });
}

Step 3: View file access list​

A GET request is sent to /api/2.0/files/file/:fileId/protectusers.

It returns a list of users and their access levels for the file.

function getProtectedFileUsers(fileId) {
  const url = `https://${API_HOST}/api/2.0/files/file/${fileId}/protectusers`;
  return fetch(url, {
    method: 'GET',
    headers: HEADERS,
  })
    .then(async (res) => {
      if (res.status === 200) return res.json();
      const text = await res.text();
      console.log(`Protected file users retrieval failed. Status code: ${res.status}, Message: ${text}`);
      return null;
    })
    .catch((err) => {
      console.log(`Protected file users retrieval error: ${err.message}`);
      return null;
    });
}