Users represent an individual's account on Box.
- Get User Information
- Get the Current User's Information
- Create An Enterprise User
- Get the Avatar for a User
- Upload user avatar
- Delete user avatar
- Create An App User
- Update User
- Delete User
- Invite User to Enterprise
- Get Email Aliases
- Add Email Alias
- Remove Email Alias
- Get Enterprise Users
- Transfer User Content
To get information about a user, call the user.get(*, fields=None, headers=None, **kwargs) method.
This method returns a new User object with fields populated by data from the API.
user_id = '33333'
user = client.user(user_id).get()You can specify which fields on the User object you want by passing an Iterable of field names:
user_id = '33333'
user = client.user(user_id).get(['id', 'name', 'login', 'is_sync_enabled'])
if user.is_sync_enabled:
print(f'User {user.id} has sync enabled')To get the current user, call client.user(user_id='me') to create the User object and
then call user.get(*, fields=None, headers=None, **kwargs) to retrieve the user information from the API.
current_user = client.user().get()To create an enterprise user, call the client.create_user(name, login, **user_attributes) method.
This method returns a new User object.
new_user = client.create_user('Temp User', 'user@example.com')To get the avatar for a user call the user.get_avatar() method with the User
object for the user you wish to retrieve an avatar for. This will return the user avatar to you in bytes.
avatar = client.user('33333').get_avatar()To add or update the avatar for a user, call the user.upload_avatar(image_path) method with the User.
Put the path to your image as a method parameter. The supported image extensions are jpg, jpeg and png.
The image size cannot exceed 1024 * 1024 pixels or 1MB.
avatar_urls = client.user('33333').upload_avatar(image_path='path/to/the/image.png')In return, you will get links to several representations of an avatar within Box account.
Alternatively you can upload the avatar by passing the image byte stream and the image extension to
the method upload_avatar_stream(image_stream, image_extension):
image_stream = open('path/to/the/image.png', 'rb')
avatar_urls = client.user('33333').upload_avatar_stream(image_stream=image_stream, image_extension='png')To delete the user avatar image use delete_avatar() method with the User.
client.user('33333').delete_avatar()Custom applications may create App Users, which represent a "headless" user managed exclusively by the application. These users can only be accessed via the API, and cannot login to the web application or other Box services.
To create a new app user, call client.create_user(name, login=None, **user_attributes) without a
login value. This returns the User object for the new app user.
new_app_user = client.create_user('App User 123', login=None)To update a user object, call the user.update_info(data=data_to_update) method with a dict of fields to update
on the user.
user_id = '33333'
user = client.user(user_id)
updated_user = user.update_info(data={'name': 'Smart User'})To delete a user call the user.delete(notify=True, force=False) method. The method returns True to
indicate that the deletion succeeded.
The notify parameter determines whether the user should receive an email about the deletion,
and the force parameter will cause the user to be deleted even if they still have files in their account. If force
is set to False and the user still has files in their account, the deletion will fail.
user_id = '33333'
client.user(user_id).delete(force=True)To invite an existing user to join an Enterprise call the enterprise.invite_user(user_email) method. This
method returns an Invite object representing the status of the invitation.
enterprise = client.get_current_enterprise()
invitation = enterprise.invite_user('user@example.com')To get a user's email aliases call the user.get_email_aliases(limit=None, fields=None) method.
This method returns a BoxObjectCollection used to iterate over the collection of
EmailAlias objects.
user_id = '33333'
user = client.user(user_id)
email_aliases = user.get_email_aliases()
for alias in email_aliases:
print(f'User {user.id} has email alias {alias.email}')To add an email alias for a user, call the user.add_email_alias(email) method with the email
address to add as an email alias for the user. This will allow the user to log in and be collaborated by this email
in addition to their login email address. Not all emails addresses can be added as email aliases. Email addresses whose domains match the domain of the login email address can always be made aliases. Email addresses whose domains differ from the domain of the login email address can be made aliases depending on the Box account configuration. The method returns an EmailAlias object.
user_id = '33333'
user = client.user(user_id)
email_alias = user.add_email_alias('alias@example.com')To remove an email alias from a user, call the user.remove_email_alias(email_alias) method with
the EmailAlias object to remove. The method returns True to signify that the removal succeeded.
user_id = '33333'
email_alias_id = '12345'
user = client.user(user_id)
email_alias = client.email_alias(email_alias_id)
user.remove_email_alias(email_alias)To get the users in an enterprise, call
client.users(limit=None, offset=0, filter_term=None, user_type=None, fields=None). You can specify
a filter_term to filter on the user's name and login fields, or select a user_type to filter down to only
managed or external users. This method returns a BoxObjectCollection used to iterate over
the collection of User objects.
users = client.users(user_type='all')
for user in users:
print(f'{user.name} (User ID: {user.id})')To move all of a user's content to a different user, call the
user.transfer_content(self, destination_user, notify=None, fields=None) method with the
User object representing the destination user. This will create a new folder in the destination user's
account, containing all files and folders from the original user's account; the method returns a
Folder object representing this new folder in the destination user's account.
source_user_id = '33333'
destination_user_id = '44444'
user = client.user(source_user_id)
destination_user = client.user(destination_user_id)
folder = user.transfer_content(destination_user)
print(f'Created new folder "{folder.name}" in the account of user {destination_user.id}')