OAuth or JWT Authentication for server-side SaaS import of configuration files and export of reports?

Our Use Case:

We are a SaaS vendor with security concious enterprise customers. We recommend that our customers connect their cloud storage provider (e.g., Google Drive) so that we can import configuration files and export report files. We would like to add Box to our list of supported cloud storage providers. We would be implementing a Box custom app.

Our current recommendation to our customers for other cloud storage providers:

  1. Create a cloud storage user account specifically for our app, with access only to folders intended for import/export.
  2. From within our application, the organization admin enables the integration to their cloud storage provider (we have a plugin/app concept).
  3. On integration enablement, we start an OAuth2 flow; the customer enters the user described above, and we obtain the temporary code (i.e., ?code=… on the redirect).
  4. We immediately send the temporary code to our server.
  5. The server exchanges the temporary code for a refresh token (i.e., this is to avoid the client_secret being exposed via our single page app).
  6. The refresh token is persisted in our database.
  7. Periodically, a daemon process will exchange the refresh token for an access token and check for new files in the import folder using the cloud storage API. Based on certain triggers, new files are uploaded to the export folder, once again by exchanging the refresh token for an access token and invoking the cloud storage API.

This seems to be similar to the service account (automation user) flow described in the Box documentation.

Our first question: should we implement the integration as we’ve outlined above, or should we use the service account flow?

If we are using the service account flow, is the following correct:

  1. We would implement JWT authentication.

  2. We would publish our app to the Box App Gallery.

  3. A Box enterprise-admin for our customer would install and enable our Box app in their enterprise. This would give them a unique service user email address.

  4. From within our app, the customer would enter the service user email address, which we would persist as part of their organization’s configuration.

  5. Our daemon process and the triggered workflows would use the JWT server-to-server authentication.

  6. We understand from blog posts that at the time this is being written, JWT authentication is not available via the free developer account. We don’t mind paying for a small enterprise for development; will a 3-user Business Start plan work, a 3-user Business plan, or something else?

If we are using the OAuth2 flow, we had some questions regarding the refresh token:

  1. We noted that a refresh token can only be exchanged once and that it expires after 60 days.
  2. We followed your docs and spun up the client-side OAuth flow pretty easily, but we haven’t implemented the server-side exchange, so we’re not sure exactly what the refresh token exchange looks like. Is it the case that each time you exchange a refresh token you receive an access code and a new refresh token? If so, is the new refresh token good for another 60 days? Other providers, have an additonal property access_type=offline that is passed on the initial OAuth request. This is not mentioned in your docs, will our server be able to exchange token without a browser?

Also, we would like to clarify the best practices we recommend to our customers. We recommend that reports be stored in their cloud storage account so that they then have complete control over the sharing and retention policy for these reports. For example, we generate reports that contain PHI and must be shared only with certain individuals. We advise our customers to share the export folder with the appropriate personnel using groups or role-based access control and that they use the data retention policies of the cloud storage provider to ensure that the reports are deleted after a certain period of time. Note that we are using “export folder” generically. There are sub-folders for different types of reports and they are typically produced daily with a date-based naming convention. Do you have any guidance for how our customers should configure their box account given this use case?

Hi @robtimism

Welcome to the forum!

Let me try to address this step by step

Pricing can be opaque, even for a Box employee, the are many feature segmentations. From the perspective of having an app authentication configured as JWT or CCG, you’ll need access to the administration console, which is available in the Business Starter.

However, my recommendation is that you do the 14 day trial, make a few tests, discover what your app will need, and cancel or upgrade as you see fit.

To authenticate using JWT you’ll need more than the service account generated email.
Here is a config file sample, you can use the config file directly or pass each parameter individually:

  "boxAppSettings": {
    "clientID": "",
    "clientSecret": "",
    "appAuth": {
      "publicKeyID": "",
      "privateKey": "",
      "passphrase": ""
  "enterpriseID": "",
  "webhooks": {
    "primaryKey": "",
    "secondaryKey": ""

This is managed on the app configuration:

Tou can take a look at the JWT set documentation here:

Using the OAuth 2.0 authentication the user must explicitly grant access to the application for their box account. There are several scopes, but some form of explicit authorization must exist.
This is where the code exchange happens.

From this point on you get an access token and a refresh token.
The access token is valid for 60 minutes, while the refresh token is valid for 60 days.
While the refresh token is valid the user does not need to re-authorize the application, if the token expires the user must re-authorize the app.
When your app requests a token refresh within the 60 days period, it gets a new access token and a new refresh token. This means the refresh token is single use.
This process does not require user intervention.

There is a nuance here. Assuming the app stores the access and refresh token somewhere (local cache/database), there is the possibility that the same client and user is requesting a refresh token at the same time, before your app has time to complete the cache update with the new tokens pair.

To get around this, if the app has a valid refresh token, and requests a token refresh, using the same access and refresh token, multiple times, then it will get the same new access and refresh token pair.

Yes. As long as the refresh token is valid, your app will get a fresh access and refresh token pair, without user intervention. If the access token is still valid your app won’t even need to refresh it.
So if your app is doing something like running a process without user intervention as long as the above is true, it will work.

Here is an interesting quote from an interesting post in Stackoverflow:

The truth about offline access

The thing is that in a lot of cases the authentication server will return the refresh token to you no matter what: You don’t have to actually ask for anything – it gives it to you. Giving you the ability to access the users data when they aren’t around. Users don’t know that you could access their data without them being there.

This is our case.

As a side note we have created an OAuth 2.0 sample app that illustrates a lot of the above:

This is a vast topic, and very dependent on your customers specific context. The best thing to do here is advise your customers to contact their box account manager.
However there is a lot of generic information about Box and HIPAA.

Hope this helps, let us know.

Thank you for your very thorough reply.

It seems that either the JWT or the OAuth flow will work for us. We are planning on implementing the JWT flow.

Given our use case, do you have an opinion on whether this is the right decision, or is it a toss-up, or is OAuth the better call?

Hi @robtimism

It depends a lot on what your application is doing and how do you expect your users to interact with those files.

For example do you expect the users to go into the box.com and see the files they interacted with when using your app?

You customers might also give you a better sense of what they want, will the administrators easily give you a JWT app with a fairly powerful service user or would they prefer to have each user to explicitly grant permissions to their security context.

From a Box SDK perspective both of these are fairly strait forward, you set them when you create the client object, and all other functionality depends on this objec. You may want to defer the option selection to later, or keep both options on the table, until you have some customer feedback to what fits better.


Thanks again. Replying here to both close the loop and in case it helps the next person.

About the use case:

  • We have high level access to IT (the CIO)
  • Users will want to see the reports our app generates from within their box.com accounts.
  • The IT organization will NOT want users to individually authenticate, and I suspect in most cases they will be locked out from doing so.
  • I don’t think they will have an issue with the JWT account as long as we are scoped to a specific folder and sub-folder. If I understand correctly, that’s straightforward to do so? i.e., we store to “acme-saas-app/” which is shared with the group “approved-users-who-can-access-acme-saas-app-reports”.

Given above, will take the advice of designing for both alternatives, but it seems like JWT is the better fit.

Please let me know if I’m on-track/off-track.


I agree, this way the JWT can make the reports available either individually or by groups as you see fit, and not require the user to authenticate on your app.

I’m getting curious about your app, keep us posted!



We ended up implementing the JWT app and had an interesting call with our enterprise client yesterday.

They shared that with other vendors, they simply enabled the Box folder for ftps. They asked what the advantages of a Box app over ftps would be.

Note that in our current use case we are primarily using the Box folder for report export and configuration import, so I can understand their point of view.

Could you share your thoughts?


That is one of those tricky questions.

If all you’re doing is sending and receiving files, I guess there is no immediate advantage.

Using a box app and specific for files you can:

  • keep versions of the files
  • immediately shared with collaborators or groups
  • trigger other integrations, slack for example
  • trigger workflows or tasks

So it looks like there can be some added value to your solution relative to the other vendors.