Friday, March 8th, 2013

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

By

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, rhaegar@box.com. 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 rhaegar@box.com i.e.

curl https://api.box.com/2.0/folders/0/items \
-H "Authorization: Bearer ACCESS_TOKEN_OF_THE_ADMIN" \
-H "On-Behalf-Of: rhaegar@box.com"

the response would be the root folder of rhaegar@box.com, 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 emailing us with your use case.

By

See all of Sean's articles.

  • Name

    Could you ask him to clearly define testing before he starts?

  • Marco

    Awesome new feature!

  • DAVE JEMISON

    i juss wanted to say somehting … :)

  • Igal

    I have tried the API call above (with our
    Enterprise admin account), but consequentially the following error obtained:

    403, …,WWW-Authenticate: Bearer
    realm=”Service”, error=”insufficient_scope”,
    error_description=”The request requires higher privileges than provided by
    the access token.”

    The case was transferred to support, but somehow it takes time to resolve
    this issue…

    • Igal

      Well, it was fixed and working. The problem was the permissions of the admin.
      Great!

  • Nitin Pawar

    Igal what permission of admin Could you please elaborate

  • Nitin Pawar

    I am stuck for both on-Behalf-Of and As-User feature both returning me 403 forbidden when tried curl as mentioned in the box docs v2