Skip to content

Latest commit

 

History

History
311 lines (266 loc) · 9.15 KB

users.md

File metadata and controls

311 lines (266 loc) · 9.15 KB

Users

Users represent an individual's account on Box.

Get User's Information

To get a user call the users.get(userID, options, callback) method.

client.users.get('33333')
    .then(user => {
        /* user -> {
            type: 'user',
            id: '33333',
            name: 'Example User',
            login: 'user@example.com',
            created_at: '2012-03-26T15:43:07-07:00',
            modified_at: '2012-12-12T11:34:29-08:00',
            language: 'en',
            space_amount: 5368709120,
            space_used: 2377016,
            max_upload_size: 262144000,
            status: 'active',
            job_title: 'Employee',
            phone: '5555555555',
            address: '555 Office Drive',
            avatar_url: 'https://app.box.com/api/avatar/deprecated' }
        */
    });

Requesting information for only the fields you need with the fields option can improve performance and reduce the size of the network request.

// Only get information about a few specific fields.
client.users.get('123', {fields: 'name,login'})
    .then(user => {
        /* user -> {
            type: 'user',
            id: '33333',
            name: 'Example User',
            login: 'user@example.com' }
        */
    });

Get the Current User's Information

To get the current user call the users.get(userID, options, callback) method with the CURRENT_USER_ID constant.

client.users.get(client.CURRENT_USER_ID)
	.then(currentUser => {
		/* currentUser -> {
            type: 'user',
            id: '33333',
            name: 'Example User',
            login: 'user@example.com',
            created_at: '2012-03-26T15:43:07-07:00',
            modified_at: '2012-12-12T11:34:29-08:00',
            language: 'en',
            space_amount: 5368709120,
            space_used: 2377016,
            max_upload_size: 262144000,
            status: 'active',
            job_title: 'Employee',
            phone: '5555555555',
            address: '555 Office Drive',
            avatar_url: 'https://app.box.com/api/avatar/deprecated' }
        */
	});

Get User Avatar

Calling users.getAvatar(userID, callback) will yield a Readable stream over the bytes of the user's avatar image.

client.users.getAvatar('22222')
    .then(avatarImageStream => {

        avatarImageStream.on('data', bytes => {
            // read avatar image bytes
        });
    });

Set User Avatar

Calling users.setAvatar(userID, avatar, callback) will set user's avatar with the input file.

const fs = require('fs');
var readStream = fs.createReadStream('image.jpg');
client.users.setAvatar('22222', readStream).then(result => {
    // read avatar urls
});

Delete User Avatar

Calling users.deleteAvatar(userID, callback) will delete the user's avatar.

client.users.deleteAvatar('22222', () => {
    console.log('User avatar deleted!'); 
});

Update User

To update a user call the users.update(userID, updates, callback) method where updates contains the fields to update.

client.users.update('33333', {name: 'New Name', job_title: 'New Title', phone: '555-1111'})
    .then(user => {
        /* user -> {
            type: 'user',
            id: '33333',
            name: 'New Name',
            login: 'user@example.com',
            created_at: '2012-03-26T15:43:07-07:00',
            modified_at: '2012-12-12T11:34:29-08:00',
            language: 'en',
            space_amount: 5368709120,
            space_used: 2377016,
            max_upload_size: 262144000,
            status: 'active',
            job_title: 'New Title',
            phone: '555-1111',
            address: '555 Office Drive',
            avatar_url: 'https://app.box.com/api/avatar/deprecated' }
        */
    });

To change a user's login email, update the login parameter on the user. Note that the new email address must already be added as a verified email alias for the user.

client.users.update('33333', { login: 'newemail@example.com' })
    .then(user => {
        /* user -> {
            type: 'user',
            id: '33333',
            name: 'New Name',
            login: 'newemail@example.com',
            created_at: '2012-03-26T15:43:07-07:00',
            modified_at: '2012-12-12T11:34:29-08:00',
            language: 'en',
            space_amount: 5368709120,
            space_used: 2377016,
            max_upload_size: 262144000,
            status: 'active',
            job_title: 'New Title',
            phone: '555-1111',
            address: '555 Office Drive',
            avatar_url: 'https://app.box.com/api/avatar/deprecated' }
        */
    });

Delete User

To delete a user call the users.delete(userID, options, callback) method. If the user still has files in their account and the force parameter is not sent, an error is returned.

client.users.delete('33333')
    .then(() => {
        // deletion succeeded — no value returned
    });
// Delete the user even if they still have files in their account
client.users.delete('123', {force: true})
    .then(() => {
        // deletion succeeded — no value returned
    });

Get Email Aliases

To get a users email aliases call the users.getEmailAliases(userID, callback) method.

client.users.getEmailAliases('33333')
    .then(emailAliases => {
        /* emailAliases -> {
            total_count: 2,
            entries: 
            [ { type: 'email_alias',
                id: '1234',
                is_confirmed: true,
                email: 'user+foo@example.com' },
                { type: 'email_alias',
                id: '1235',
                is_confirmed: true,
                email: 'user+bar@example.com' } ] }
        */
    });

Add Email Alias

To add an email alias for a user call the users.addEmailAlias(userID, email, callback method.

client.users.addEmailAlias('33333', 'user+baz@example.com')
    .then(alias => {
        /* alias -> {
            type: 'email_alias',
            id: '12345',
            is_confirmed: false,
            email: 'user+baz@example.com' }
        */
    });

Enterprise admins can automatically confirm the email alias via the is_confirmed option:

client.users.addEmailAlias('33333', 'user+quux@example.com', {is_confirmed: true})
    .then(alias => {
        /* alias -> {
            type: 'email_alias',
            id: '12346',
            is_confirmed: true,
            email: 'user+quux@example.com' }
        */
    });

Delete Email Alias

To delete a users email alias call the users.removeEmailAlias(userID, aliasID, callback) method.

var userID = '33333';
var aliasID = '12345';
client.users.removeEmailAlias(userID, aliasID)
    .then(() => {
        // removal successful — no value returned
    });

Terminate users session

To terminate user's sessions call the users.terminateSession(options, callback) method.

var userIDs = ['33333', '44444'];
var userLogins = ['user1@example.com', 'user2@example.com'];

client.users.terminateSession({
    user_ids: userIDs,
    user_logins: userLogins
}).then((result) => {
        /* result -> {
            message: "Request is successful, please check the admin events for the status of the job" }
        */
    });