29 May 2019

Mastering the "Authorize application" page

As a user, you want to know which permissions the app is requesting and what does it mean to your data. As an app developer, you just want to ask for the permissions you need. Right? This comes together at the "Authorize application" page, so our app needs to understand what's going on. Note that applies to 3-legged OAuth. 

Here are a few scenarios to consider:

Read Data Management folders and files (e.g. from BIM 360 Document Manager)

In this case, the app need data:read scope. That's the minimum that most apps will use. 

data:read scope

Read Data Management + View models

In this case, we see a "Others: view your viewables", which reflects the viewables:read scope and is the recommended way to send the access token to the client for Viewer. Note that viewables:read is a subset of data:read, but you need to explicitly use it. It's also recomended that you create 2 access tokens, one with data:read/viewables:read and another with only viewables:read, and use that to send to the client. 

If your app is proxying this access token, data:read allow access to viewables, so no need to scope viewables:read.

data:read & viewables:read scope

Write data to Data Management (e.g. upload models to BIM 360)

In this case, your app most likely needs data:create and data:write. Also data:read. Now the message shows more on Data.

data:read, data:create and data:write scopes

What if my app also needs to create and manage buckets (2-legged) or use Design Automation?

Buckets belong to the app and are created with 2-legged tokens, right? Ideally, your app should create a second access token using only the application credentials, not the user credentials. 

This is something your app SHOULD NOT DO, it results in a confusing page:

bucket:read mixed with user permissions

Another example is with code:all scope, used for Design Automation. If your app GET and/or PUT user data on BIM 360, it needs only data:read/write/create, the Design Automation should run with a different access token. See below how this scope reflects in the page:

code:all scope mixed with user permissions

As a general rule, use the minimum set of scopes your app needs, that's a security best practice! 

Related Article