Skip to main content

Update user role

This example demonstrates how to automate user onboarding in ONLYOFFICE DocSpace using the API. It covers creating a user, retrieving their profile, and updating their role.

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(`User creation failed. 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(`User retrieval failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }

  const userData = await res.json();
  console.log('User retrieved:', userData);
  return userData;
}

// Step 3: Update user role
async function updateUserRole(userId, role) {
  const url = `${API_HOST}/api/2.0/people/${userId}`;
  const res = await fetch(url, {
    method: 'PUT',
    headers: HEADERS,
    body: JSON.stringify({ role }),
  });

  if (!res.ok) {
    const t = await res.text();
    console.log(`User role update failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }

  console.log(`User ${userId} role updated to ${role}`);
}

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

  if (userId) {
    await getUser(userId);
    await updateUserRole(userId, 'Manager');
  }
})();

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(`User creation failed. 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(`User retrieval failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }

  const userData = await res.json();
  console.log('User retrieved:', userData);
  return userData;
}

Step 3: Update user role​

A PUT request is sent to /api/2.0/people/:userid.

The request updates the user's profile, applying the new role or permissions.

async function updateUserRole(userId, role) {
  const url = `${API_HOST}/api/2.0/people/${userId}`;
  const res = await fetch(url, {
    method: 'PUT',
    headers: HEADERS,
    body: JSON.stringify({ role }),
  });

  if (!res.ok) {
    const t = await res.text();
    console.log(`User role update failed. Status code: ${res.status}, Message: ${t}`);
    return null;
  }

  console.log(`User ${userId} role updated to ${role}`);
}