To interact with the Box API, i.e. to use
boxr, requires two things:
You can think of a Box-app as the door through which
boxr functions access Box. There are two different types of apps, described in the apps overview-vignette.
The focus of this article is the interactive-app, designed (unsurprisingly) for interactive use. You authenticate to this app using the “OAuth Dance” on your local computer. Then, you can use
boxr with the privileges of your Box user-account.
How you use this article depends on your Box set-up. We cover these situations:
Someone in your Box organization has already created an interactive-app. This means that you have been provided with two character strings that correspond to
If so, you need only the section focused on users.
You need to create a Box interactive-app, as described in the create section.
If your Box account is controlled by an organization, e.g. you use Box at work, Box apps may be controlled by your Box-admin team. If this is the case, you might refer them to this article as a part of a request to have an app created or approved.
To make the first authentication to using an interactive app, you must be using a local computer, such as a laptop.
If you want to use
boxr on a remote computer, e.g. using RStudio Server on a remote computer through a browser, authenticate first using a local computer, then consult the next section.
Using your provided values for
client_id and a
# supply your own "your_client_id" & "your_client_secret" box_auth(client_id = "your_client_id", client_secret = "your_client_secret")
At this point, you may be asked to participate in the “OAuth Dance”; a browser window may open to a Box page asking you if it’s OK to authenticate. Say “yes”. All being well, in the R console window, you will receive a response like this:
Waiting for authentication in browser... Press Esc/Ctrl + C to abort Authentication complete. boxr: Authenticated using OAuth2 as Ian Lyttle (firstname.lastname@example.org) ● You may wish to add to your `.Renviron` file: BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret [Copied to clipboard] ● To edit your `.Renviron` file: - `usethis::edit_r_environ()` - check that `.Renviron` ends with a newline
You are authenticated to Box for the remainder of your R session.
To make things easier for subsequent R sessions, you can add this information as R environment-variables, by following the advice in the response:
.Renviron file; you can use
Paste the lines copied to your clipboard, make sure
.Renviron ends with an empty line.
.Renviron, restart R.
Now, you can run
box_auth() without arguments, and it should just work.
# restart R library("boxr") box_auth()
Using `BOX_CLIENT_ID` from environment Using `BOX_CLIENT_SECRET` from environment boxr: Authenticated using OAuth2 as Ian Lyttle (email@example.com)
Because the “OAuth Dance” requires you to use a local computer, this can cause some difficulties when you use a remote computer, i.e. if you are using RStudio Server or RStudio Cloud. There are a couple of ways around this:
In this section, we look at the first option.
As always, keep security in mind. Presumably, if you are using RStudio Server, it is running on a computer over which you (or your institution) has administrative control. This presents a different set of security considerations from the case where you’re using RStudio Cloud, where neither you nor your institution (unless you work for RStudio) has administrative control of the machine. Keep in mind that the
.boxr-auth file allows its bearer the much the same Box privileges as the user it represents.
Before beginning the transfer-process, make sure that the R installations on your local computer (where you generate the token) and the remote computer have the same version of the httr package (ask me how I found out).
...at the right edge, then specify
~for the home directory.
.boxr-oauthfrom your local computer (you need to be able to view “hidden” files).
.Renvironfile to add the environment variables
BOX_CLIENT_SECRET- using the values from the
.Renvironfile on your local computer. You may find the function
usethis::edit_r_environ()to be useful.
If you are using RStudio Cloud, it is very important that you upload
.boxr-oauth to your home directory, which is nominally private to your account, rather than the project directory, which may be shared.
.boxr-oauth is uploaded, and you have restarted your R session, you should be able to run
boxr::box_auth() on the remote computer and it should just work, like on your local computer.
Keep in mind that to create or activate a Box App, you may need the approval of your Box-admin team. If you have a personal Box account, you are your Box-admin team.
This material is a summary of the Box documentation on OAuth 2.0 apps.
Having logged into your account in a browser, start at the Box Developers Console.
Click on the button Create New App, which will guide you through four screens to create your new app:
View Your App will take you to the Box Developers Console.
You will be in the Configuration sub-menu by default:
This is where you can find
At this point, you have enough information to use