Although this function can be used in all sorts of situations, it can be particularly useful in setting up a workflow with a service-account:

  • If you are authenticated as a user, using box_auth(), you can invite the service account to collaborate on a folder in your user filespace. In this case, the shared folder will appear in the service-account filespace.

  • If you are authenticated as the service-account using box_auth_service(), you can invite your user-account to collaborate. In this case, the shared folder will appear in your user file-space.

Once you issue an invitation to create a collaboration, you cannot change it, e.g. you cannot change the role from "viewer" to "co-owner". However, you can delete the collaboration, then issue a new invitation. To delete a collaboration, use box_collab_delete(). To check a Box folder ID or file ID for existing collaborations, use box_collab_get(). You can also use the Box web-portal to manage collaborations.

The default role, i.e. permission level, for an invitation is "editor". Legal values for role are "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner", "owner".

  dir_id = NULL,
  user_id = NULL,
  file_id = NULL,
  group_id = NULL,
  login = NULL,
  role = "editor",
  can_view_path = FALSE



numeric or character, folder ID at Box.


character ID for Box user-account to invite.


numeric or character, file ID at Box.


character ID for Box group-account to invite.


character email address of account to invite, if specified will be used instead of user_id.


character role of the collaborator; default is "viewer".


logical indicates to allow the collaborator to navigate parent-folders at Box.


Object with S3 class boxr_collab.


To use this function, you must provide exactly one of: dir_id or file_id, to specify what you want to share, and exactly one of: user_id, group_id, or login (email address), to specify the account you want to share it with.

While authenticated from the host account, the one that will issue the invitation, you can use box_ls() and box_setwd() to get the dir_id or file_id for the item you want to share. If the host-account is the user-account, you can also use the web-portal to find the dir_id or file-id. If the host account is the service-account, you can use the Box content-portal to find this.

A user can find their user_id using the Box web-portal. As well, when you authenticate using boxr, the user_id is included in the login message. Thus, you can use box_auth_service() to find out the user_id for a given service-account.

This returns an object with S3 class boxr_collab; this is a list containing the response from the API. You can use as_tibble() or on this return-object to convert to a tibble or data frame.

See also