Announcing 'On Behalf Of', the Simplest, Most Powerful Admin API You'll Ever Use

Notice: As-User has replaced the previous On-Behalf-Of functionality. As-User is more robust because it is tied to a static user_id instead of a dynamic email address that may change. On-Behalf-Of functionality will continue to be supported, but we recommend migrating to the As-User header.  Please refer to the documentation for further details.

When an admin of a Box enterprise account logs into the admin console, she gets to see a list of all of the users in that enterprise. The admin can go through this list and change various settings for each user, such as the email address they have associated with that account.

The Box API already provides access to these settings through the various methods on our /users endpoint. However, there is one additional feature in the admin console that hasn't yet been exposed through the API, the 'Log in to this account' feature.

When the admin clicks this link for a particular user, they're automatically logged in to the account of that particular user i.e.

Once the admin is logged in as that particular user, she can perform any action on behalf of that user, such as creating folders, deleting items, rearranging the account, and so on. Anything the individual user can do in their own account can now be done by the admin.

As of today, you can also do this through the API! We've created a special header called "On-Behalf-Of" that enables the same functionality you have in the admin console, except through the API. Whenever you include the "On-Behalf-Of" header as an admin, you'll effectively be making API calls as the user indicated in the "On-Behalf-Of" header. Anything the individual user can do in their own account through the API can now be done by the admin through the API. This has many practical applications, including simple tasks such as pre-configuring a user's account, as well as more involved processes like implementing Data Loss Prevention systems.

Here's a more in-depth example of how to use the API. Let's say you're an admin of an enterprise account, and you would like to get a list of items that are in the root folder of one of your users, After authenticating an admin account through OAuth 2, you would set up the API call as a normal GET /folders/{id}/items call except you will also include an "On-Behalf-Of" header indicating that you want to do this on the behalf of i.e.

[bash]curl \
-H "Authorization: Bearer ACCESS_TOKEN_OF_THE_ADMIN" \
-H "On-Behalf-Of:"[/bash]

the response would be the root folder of, not that of the admin. This functionality extends to any endpoint the user could access through the API by themselves e.g. /folders, /files/ /events and more.

On-behalf-of requires a special scope that must be enabled by the Box team-please let us know if you're interested in using it by submitting a case.