跳到主要内容

Manage users

This example demonstrates how to manage user accounts in ONLYOFFICE DocSpace using the API. It covers creating, retrieving, terminating, and deleting users, following a structured administrative workflow.

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 = 'https://yourportal.onlyoffice.com';
const API_KEY = 'your_api_key';

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

// Step 1: Create a new user
async function createUser(firstName, lastName, email) {
  const url = `${API_HOST}/api/2.0/people`;
  const res = await fetch(url, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify({ firstName, lastName, email }),
  });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Failed to create user. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  const json = await res.json();
  const userId = json?.response?.id;
  console.log(`User created successfully: ${userId}`);
  return userId;
}

// Step 2: Retrieve a user by ID
async function getUser(userId) {
  const url = `${API_HOST}/api/2.0/people/${userId}`;
  const res = await fetch(url, { method: 'GET', headers: HEADERS });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Failed to retrieve user. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  const userData = await res.json();
  console.log('User retrieved:', userData);
  return userData;
}

// Step 3: Terminate a user
async function terminateUser(userId) {
  const url = `${API_HOST}/api/2.0/people/status/Terminated`;
  const res = await fetch(url, {
    method: 'PUT',
    headers: HEADERS,
    body: JSON.stringify({ userIds: [userId], resendAll: false }),
  });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Failed to terminate user. Status code: ${res.status}, Message: ${t}`);
    return;
  }
  console.log(`User ${userId} terminated successfully`);
}

// Step 4: Delete user profile
async function deleteUser(userId) {
  const url = `${API_HOST}/api/2.0/people/${userId}`;
  const res = await fetch(url, { method: 'DELETE', headers: HEADERS });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Failed to delete user. Status code: ${res.status}, Message: ${t}`);
    return;
  }
  console.log(`User ${userId} deleted successfully`);
}

// Run
(async () => {
  const userId = await createUser('John', 'Doe', 'john.doe@example.com');
  if (userId) {
    await getUser(userId);
    await terminateUser(userId);
    await deleteUser(userId);
  }
})();

Step 1: Create a user​

A POST request is sent to /api/2.0/people with:

  • firstName: The user's first name.
  • lastName: The user's last name.
  • email: The user's email address.

The API returns a user ID, which is required for further operations.

async function createUser(firstName, lastName, email) {
  const url = `${API_HOST}/api/2.0/people`;
  const res = await fetch(url, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify({ firstName, lastName, email }),
  });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Failed to create user. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  const json = await res.json();
  const userId = json?.response?.id;
  console.log(`User created successfully: ${userId}`);
  return userId;
}

Step 2: Retrieve a user by ID​

A GET request is sent to /api/2.0/people/:userId to fetch user details.

The response includes the user's profile information such as name, email, and assigned roles.

This step ensures that the user exists before making any updates or deletions.

async function getUser(userId) {
  const url = `${API_HOST}/api/2.0/people/${userId}`;
  const res = await fetch(url, { method: 'GET', headers: HEADERS });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Failed to retrieve user. Status code: ${res.status}, Message: ${t}`);
    return null;
  }
  const userData = await res.json();
  console.log('User retrieved:', userData);
  return userData;
}

Step 3: Terminate a user​

A PUT request is sent to /api/2.0/people/status/Terminated.

The request includes:

  • userIds: A list of user IDs to be terminated.
  • resendAll: False — Do not send notifications.

The API marks the user as terminated, meaning they cannot log in but are still present in the system.

async function terminateUser(userId) {
  const url = `${API_HOST}/api/2.0/people/status/Terminated`;
  const res = await fetch(url, {
    method: 'PUT',
    headers: HEADERS,
    body: JSON.stringify({ userIds: [userId], resendAll: false }),
  });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Failed to terminate user. Status code: ${res.status}, Message: ${t}`);
    return;
  }
  console.log(`User ${userId} terminated successfully`);
}

Step 4: Delete a user profile​

A DELETE request is sent to /api/2.0/people/:userId.

The API removes the user permanently, making them unrecoverable.

This step is essential for offboarding employees or cleaning up unused accounts.

async function deleteUser(userId) {
  const url = `${API_HOST}/api/2.0/people/${userId}`;
  const res = await fetch(url, { method: 'DELETE', headers: HEADERS });
  if (!res.ok) {
    const t = await res.text();
    console.log(`Failed to delete user. Status code: ${res.status}, Message: ${t}`);
    return;
  }
  console.log(`User ${userId} deleted successfully`);
}