Box Service-Apps

Using a Service App

A service app is often created in support of a single task, e.g. run a set of daily-reports. Because a service-app acts of behalf of the system itself, and because the tokens are portable, it is a common practice to limit the scope of a service-app to a single folder or small set of folders. Thus, you might be dealing with multiple service-apps if you are working on multiple projects.

This is why we encourage you to create a directory in your home directory, called .boxr-auth, to contain these tokens.

library("fs")

# mode 700 restricts access to your account
dir_create("~/.boxr-auth", mode = 700)

When you receive JWT (token) file for your first service-app, save it to your local computer as ~/.boxr-auth/token.json.

To authenticate to Box using this token:

box_auth_service()

boxr: Authenticated using OAuth2 (JWT) as boxr-jwt-ijl ([email protected], id: 9862360558)

The authentication function box_auth_service() takes token_file as an argument. Its default is the value of the environment variable BOX_TOKEN_FILE; if that does not exist, the default becomes ~/.boxr-auth/token.json.

In mid-2020, we noticed some issues with box_auth_service() failing intermittently, for no apparent reason; our best guess is that the clocks at either end of the authentication process can fall out-of-sync. If this happens, a workaround is made whereby a “time offset” is applied to the authentication request, which appears like this:

Failed JWT request: time offset was 0 seconds.
Retrying JWT request: time offset now -15 seconds.
Failed JWT request: time offset was -15 seconds.
Retrying JWT request: time offset now 15 seconds.
boxr: Authenticated using OAuth2 (JWT) as boxr-jwt-ijl ([email protected], id: 9862360558)

In a (near) future version of boxr, we plan to make it easier to work interactively with multiple service accounts.

library("fs")

# mode 700 restricts access to your account
dir_create("~/.boxr-auth", mode = 700)

Collaboration Workflows

If you are using a service-app (acting as a service-account), you may also want to interact with the same files using your interactive-app (acting as your user-account). By default, a service-account has access to only its own file-system, and your user-account has access only to its own (different) file-system. To solve this problem, you can invite your service-account to collaborate on a folder in your user file-system, or you can invite your user-account to collaborate on a folder in the service file-system. In either case, you can use the function box_collab_create().

Which way you go depends on the purpose of the service.

1. If the service is strongly associated with a particular user, e.g. “Nate’s service app”, you (Nate) way wish to invite your service-app to collaborate on your (Nate’s) folders.

2. If the service is associated with an ongoing task, e.g “daily-report app”, it may be best for the service to keep the files in its filesystem (Nate might win the lottery someday). If Nate wants access to the files, the service-app may “wish” to invite Nate to collaborate on its folders.

To use box_collab_create(), you need four things:

1. The user_id of the account you are inviting.

2. To be authenticated using the “host” account. This can be either the service-account or your user-account.

3. The file_id/dir_id of the Box file/folder you want to share.

4. The role (permissions) you would like to assign to the collaborator.

Here’s a concrete example. I’ll show how I can share a service-account folder with a user, but the process is easily inverted.

First, I’ll need my user_id from my user-account; I can get that by authenticating:

box_auth()

Using `BOX_CLIENT_ID` from environment
Using `BOX_CLIENT_SECRET` from environment
Auto-refreshing stale OAuth token.
boxr: Authenticated using OAuth2 as Ian Lyttle ([email protected], id: 286871517)

I note that my user_id is "286871517". Next, I’ll authenticate using my service-account:

box_auth_service()

boxr: Authenticated using OAuth2 (JWT) as boxr-jwt-ijl ([email protected], id: 9862360558)

From my service-account, I can take a look at my home-folder:

box_ls()

box.com remote object list (1 objects)

  Summary of first 1:

         name   type          id size                                              owner
1 daily_bread folder 91350609301  0 B [email protected]


Use as.data.frame() to extract full results.

There, I see that the folder I want to share, daily_bread has dir_id of "91350609301".

I decide that that I want my user account to act as "co-owner" of this folder, so now I am ready to invite my user-account to collaborate:

box_create_collab(dir_id = "91350609301", user_id = "286871517", role = "co-owner")

boxr-jwt-ijl ([email protected]) has invited Ian Lyttle ([email protected]) to collaborate on folder `daily_bread` as co-owner.

At this point, I’m done. If I want, I can authenticate to my user-account and check that I have access to the folder:

box_auth()

Using `BOX_CLIENT_ID` from environment
Using `BOX_CLIENT_SECRET` from environment
boxr: Authenticated using OAuth2 as Ian Lyttle ([email protected], id: 286871517)

box_ls()

box.com remote object list (1 objects)

  Summary of first 1:

         name   type          id size                                              owner
1 daily_bread folder 91350609301  0 B [email protected]


Use as.data.frame() to extract full results.

Creating a Service App

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 JWT apps.

Having logged into your account in a browser, start at the Box Developers Console.