When creating your application, you will be asked to choose what scopes your application requires. In general, these are scopes that will be presented to the Admin of the enterprise or to the user that is looking to utilize your application for them to review and decide if they want to approve that level of access. These scopes will largely apply when creating a "Custom Application" type with only minor differences between the different Authentication types. Namely, the two Server Authentication methods have an additional scope when compared with the User Authentication.
Our developer documentation does a great job of outlining what the different scopes are that you can choose between during the configuration but there are a few worth calling out more in depth that our partners often utilize to drive the functionality of their application.
Under the "Advanced Features" of the Configuration section, there may be one or two scopes listed depending on which authentication type you chose. User Authentication types will see a scope entitled, "Make API calls using the as-user header" and Server Authentication types will also see, "Generate user access token." Both of these have a similar function, but can often simplify your application logic when doing large scale integrations and lots of API operations on Box.
As-User Header
This scope allows you to simplify your token management process, as it gives you the ability to impersonate users without requiring a separate set of tokens. The general flow is that you have an Admin or a Co-Admin with sufficient permissions go through the OAuth process once and get a token from their perspective. If using User Authentication, you now have an Access and a Refresh token pair that you can utilize to access that account, but to access other individual accounts, you would need to have each one of them go through the same authorization process. With this header, you can utilize the one set of tokens and during your requests, pass in an extra header called "As-User" (including the id of the user you want to impersonate), and as a result, that API action will be performed from their perspective.
From an audit perspective, in our event stream we log that there was an action performed by an admin on behalf of a specific user, so there is full transparency that it was not the individual taking that action themselves. With this method, you can simplify the number of tokens you need to have for things like scanning content across an enterprise as you can get one token, a list of user ids, and then go through impersonating each one rather than having hundreds or thousands of users go through your application authorization.
Generating User Access Tokens
This one is unique to the Server Authentication types as it allows you to request a token directly from an individual's perspective when sending us the payload — note that this only works for users in enterprises where your application is authorized in, not for any user in general.
There is an important distinction between generating these access tokens and utilizing the As-User header, as with the first method, in the logs you are able to see that an admin was performing actions on behalf of a user, where in this case, you will see that an application was performing those actions for them. This defers some of the audit responsibility to the application owners that are requesting these tokens and performing actions on behalf of these users, but this is often the cleanest solution, especially if you are utilizing any client-side interactions through the API. You would not want to send a request with an admin token and an As-User header which may be logged at the browser level, but instead, use a token that is scoped only to the user that is already interacting with the content being presented. If they capture the token generated for their account by your application, they would simply be able to access the content that they already own and nothing else.
For any questions, please reach out to our Developer Forum