Demystifying Box Permissions

The other major way to get access to a file, is to be the owner of that file. Ownership flows down like a waterfall. Every folder/file you've created in your root folder is owned by you. And every file/folder inside another folder, gets the same owner as that folder. The owner has "full" permissions, though the meaning of "full" depends on their account type (free vs. paid vs. enterprise, etc.) and the enterprise configuration.

For understanding collaboration roles and permissions, these articles should help:

https://community.box.com/t5/Collaboration-and-Sharing/Folder-And-Subfolder-Permissions/ta-p/157

https://community.box.com/t5/Collaboration-and-Sharing/What-Are-The-Different-Access-Levels-For-Collaborators/ta-p/144

Permissions aren't granted directly. Instead, they are implied by collaboration roles. If you are collaborated with role R on folder F, you will be granted a certain set of permissions P1, P2, ... . Furthermore, because Box has a waterfall permissions model, these permissions P1, P2, ... will also be granted on all descendants of folder F.

The 'permissions' field on files/folders (which is documented at https://docs.box.com/reference#folder-object-1) is not something that you can directly set. It is also not a real field. Every owner/collaborator will see their own set of permissions dynamically shown for that field.

You don't need to worry about shared links, unless you are allowing users to paste a shared link into your application and go to it. If so, then you can use https://docs.box.com/reference#get-a-shared-item to query for that file/folder, and then you can see the permissions on it.

Permissions aren't granted directly. Instead, they are implied by collaboration roles.

I don't think that quite aligns with what I've observed so far. I don't see any permissions on a file that is within a folder I am a collaborator on. I also don't see any permissions on the shared folder, or its parent, all the way up the line. Instead, I have to iterate through all collaborator objects and find ones that apply to the current user and piece together the full picture of permissions myself. This is why I asked what the permissions field was for; I never seem to get into a situation where it is defined.

You don't need to worry about shared links, unless you are allowing users to paste a shared link into your application and go to it.

I don't know what you mean by this. Why don't I have to worry about shared links? If a user accesses a document in Box via a link and chooses to use my application to open it, I need to know what permission they have, and the only way to find that is to look at the shared resource associated with the link.

I understand how the "Shared" resource works on Box's end. My problem is that I cannot access the Shared resource that is associated with the link a user is accessing. Without that, I can't figure out programmatically what access level a user should have when my application gets called.

Ownership flows down like a waterfall.

Is that reflected in the database? Meaning, if I have a Folder A with a child Folder B, and I share Folder A with some permission, and then the sharee looks up the info of Folder B, will they find any collaborator information on Folder B? Or will they have to look up Folder A and look at the collaborators there to find their permissions?

I don't think that quite aligns with what I've observed so far. I don't see any permissions on a file that is within a folder I am a collaborator on. I also don't see any permissions on the shared folder, or its parent, all the way up the line.

'permissions' is an optional field, so it isn't present by default. You need to explicitly ask for it. GET /folders/id?fields=permissions, or GET /folders/id/items?fields=permissions, or GET /files/id?fields=permissions will get you the permissions.

I just tested this, and it worked for me. I created a folder F, and created a file A inside it. I then collaborated folder F with another user, with the editor role. Logged in as that user, I used the API to call GET /files/id?fields=permissions, and was able to see

'permissions': {'can_comment': True, 'can_delete': True, 'can_download': True, 'can_preview': True, 'can_rename': True, 'can_set_share_access': True, 'can_share': True, 'can_upload': True}

I then changed the role to viewer, and again called GET /files/id?fields=permissions, and was able to see

'permissions': {'can_comment': True, 'can_delete': False, 'can_download': True, 'can_preview': True, 'can_rename': False, 'can_set_share_access': False, 'can_share': True, 'can_upload': False}

Instead, I have to iterate through all collaborator objects and find ones that apply to the current user and piece together the full picture of permissions myself. This is why I asked what the permissions field was for; I never seem to get into a situation where it is defined.

Be careful when doing this. You can also be granted permissions via a group collaboration, so you also need to check all collaborations which point at any group that you are a member of.

Looking up the 'permissions' field directly should be easier.

Is that reflected in the database? Meaning, if I have a Folder A with a child Folder B, and I share Folder A with some permission, and then the sharee looks up the info of Folder B, will they find any collaborator information on Folder B? Or will they have to look up Folder A and look at the collaborators there to find their permissions?

The 'permissions' field on an item should always show the correct waterfall permissions for that item, showing the accurate set of permissions without needing to walk up the tree.

If you have a folder and you call /folders/id/collaborations, I believe, last time I tried it myself, that it gave all collaborations not just for that folder, but for all its ancestors as well. So you shouldn't need to walk up the tree, you should be able to get all collaborations just from that one API call. Note that it is a paging API, if there are too many collaborations, you'll need to page through the results with multiple API calls.

I don't know what you mean by this. Why don't I have to worry about shared links? If a user accesses a document in Box via a link and chooses to use my application to open it, I need to know what permission they have, and the only way to find that is to look at the shared resource associated with the link.

Got it. I didn't know this was part of the use-case for your app.

I understand how the "Shared" resource works on Box's end. My problem is that I cannot access the Shared resource that is associated with the link a user is accessing. Without that, I can't figure out programmatically what access level a user should have when my application gets called.

Can you explain a bit more about how your application receives the request to handle that file? What information (Box ids, shared links, etc.) are available to your application at that time?

Ah, thank you! Checking a file's permissions is much, much simpler than checking all of the collaborators, especially when you involve groups. Though, I do have to piece together their role from the permissions I see, but that's not too difficult to do.

Can you explain a bit more about how your application receives the request to handle that file? What information (Box ids, shared links, etc.) are available to your application at that time?

My application defines a Web App Integration (https://docs.box.com/docs/box-web-application-integrations/) to allow users to open documents. I currently get 4 query string parameters from Box during a file open operation: the Box file ID, the Box user ID, a url to redirect back to the user's file list, and an auth code. From these parameters alone, I can't figure out what shared link the user might be following to open the file. It works fine for permissions gained as a collaborator, though.

I don't know for sure, but my guess is that:

• If the user _only_ has access via the shared link (they aren't logged into a Box account which is already a collaborator), then they won't be able to use any web app configurations with it.
• If the user also is collaborated, then the webapp redirects them to the normal file page. So their permissions are going to be the permissions granted by their role(s), and not by the shared link.

I just tried this out. I created a folder with a word document in it, and collaborated it with someone else, as the Previewer role. I then generated a shared link, and as the collaborator, visited that shared link. Even though a shared link usually grants downloader permissions, I still only had previewer permissions.

I also visited a shared link that I was not collaborated on, and I didn't see any buttons for using a web app integration with it.

I could be wrong, so if you have any reason to doubt any of that, we can find someone more knowledgeable in this area to help you with this.

Though, I do have to piece together their role from the permissions I see, but that's not too difficult to do.

I'm also working on a client-side app at Box, and we're starting to look into permissions. We're still in the very early stages of that work, but right now we suspect that it will be much easier to build the functionality around the can_* permissions, rather than around the roles. Understanding what a role means, and how to map that to a set of application functionalities, essentially means translating that role back into a set of permissions anyway. This also means that you don't have to try and figure out which role it is, from a set of booleans. Also, if we introduce new roles in the future, your code will still work without needing to make a code change to recognize the new role.

How can you edit permissions?  `can_preview:true`.  I would like to change that to false.  We have 100,000s of items in a format not viewable by Box (and they probably never will be), we just want to turn where it says you can't view this and allow the user to continue with download.