BaseSpace Permissions

This guide describes the permission structure in BaseSpace and how your application is able to get the level of access it needs. When an application is first started it has no access to any of the user's BaseSpace data. The scope parameter, as part of the Obtaining Access Tokens workflows, allows your app to specify what resources and type of access it needs.

Permissionable Data in BaseSpace

A User's sequencing data exists within multiple resources in BaseSpace. The API Data Model Overview describes each of these resources in detail. The following are the resources that apps are able to use through the API after requesting appropriate permissions:

  • Runs - .bcl files directly from the sequencing instrument
  • Projects - contain the resources Samples and AppResults. Permissions granted to a project also extend to the data within them.
  • Samples - .fastq files, the result of demultiplexing sequencing data in BaseSpace. All permissions for Samples are inherited from the Project they are contained within.
  • AppResults - generally .bam and .vcf files, but no restriction on file types in AppResults. These are the resulting files that an app produces upon completion. All permissions for AppResults are inherited from the Project they are contained within.

Permissions That Apply to BaseSpace Resources

These are the core set of permissions applicable to the resources described above. Keep in mind that since Projects may contain Samples and AppResults, it's often simplest to request access at the project level to that level of access to the Samples and AppResults within:

  • browse access: Grants your app the ability to see metadata but not to download files. Applies to Runs, Samples, AppResults, and Projects. Samples and AppResults inherit permission from the Project.

  • read access: Allows access to see metadata and download files. read permission implies browse as well. Applies to Runs, Samples, AppResults and Projects. Samples and AppResults also inherit permission from the Project, so requesting read access to the Project will give you read access to all of the Samples and AppResults contained within the Project.

  • create access: Ability to create resources in BaseSpace. create does not also imply write, read, or browse. Currently create applies to both Projects, which allows creating AppResults, and Runs, which allows uploading a sequencing run folder.

  • write access: Ability to upload/modify metadata and files, implies create, read, and browse permission. Applies to Projects, please refer to Writing Back to BaseSpace for more information.

  • audit access: Ability to view a history feed. Use AUDIT USER scope for user and workgroup feeds, and AUDIT DOMAIN for domains feeds. This feature is only available to enterprise customers, and domain feeds are only available to domain administrators.

Permissions That Apply Globally

In addition to gaining permission to specific resources as described above, apps are also able to request global permissions. These permissions are unique in that they generally offer more permission to resources than the standard permissions listed above.

Browse Global

Rather than asking for access to specific AppResults, Samples, and Projects, you may request a browse global level of access. An app that has been granted browse global access to the user's information is able to see all of the metadata associated with the different Projects, Samples, and AppResults that users owns in BaseSpace.

An app is generally started with data selected by the user with information conveyed to your app via the App Triggering Guide process. Knowing what the user selected in BaseSpace, you may request a level of access to those specific resources. In most cases, this will eliminate the need for your app to have a data selector and thus reducing the need for browse global access.

Create Projects

When writing back to BaseSpace, the user may wish to create a new Project to write the data back to instead of writing it to an existing Project. Also, a user may not have write or create permission to the Project the data was pulled from, so apps should be prepared to create a new Project for the user should these cases arise.

To have the ability to create Projects for a user, an app needs to request the create projects scope. This permission allows an app to create Projects for a user. When your app creates a Project, your app automatically gains create access to that Project. This means that you can immediately add an AppResult to the Project that was created.

Please refer to the Writing Back to BaseSpace Guide for more information.

Create Global

The ability to create in the API means that an app is able to create certain resources or objects in BaseSpace. create global is a specific implementation of the create scope that gives an app create access to all of the Projects that the user has write access to in BaseSpace. Meaning that your app can then create AppResults within those Projects.

If, with this, your application still does not have permission to a Project to write data into, create projects should be used to create a new Project. This is described above.

Using the Scope Parameter for Gaining Access Via OAuth

As part of the OAuth process which allows your app to request rights to user data, the scope parameter is a simply comma separated string containing the needed permissions. BaseSpace uses the permissions listed in the scope parameter to display the authorization dialog which shows the user what access the app is requesting allowing them to accept or deny the request. If the user accepts, the app will get an access_token with the permissions associated with which further API calls may be made. It's important to keep in mind that apps should strive to requesting only what is absolutely required as users will (rightfully) hesitate to grant an app more access than they feel it needs to perform the work.

Please refer to Obtaining Access Tokens to get more details about the steps involved in the OAuth flows supported by BaseSpace.

Empty Scope Value

If the scope values isn't passed in or is empty, the OAuth process will still function but will result in an access_token that does not have access to any of the user's data. The only API method that the app will be able to access is GET: users/current which returns basic information about the user including their user id, name, and email address. This is the User Authentication process.

Scope Syntax

Comma separated list of global and resource permissions. Each of these has the format:

Global permission: 

<browse global | create global | create projects>

Resource permission: 

<browse | read | create | write> 
<project | run | sample | appresult > 
<id>

Examples of Scope

read project 12, browse global

translates to: read access to Project Id 12 and all Samples and AppResults it contains. In addition, browse access to all resources the user has access to

The following is an example of the OAuth dialog for an app that requests the above scope:

OAuth Dialog Example

Similarly,

read sample 234,read appresult 456

translates to: read access to Sample Id 234 and AppResult Id 456

and,

create projects,create project 12

translates to: the ability to create Projects for the user and the ability to create AppResults within Project 12

Subsequent Permission Requests

Requesting More Access

For many apps that operate on data that users select in BaseSpace, it will be necessary to request additional access from the user upon subsequent runs. The process for requesting access to additional data isn't any different than the initial request, but the scope will be different. This is described in Obtaining Access Tokens.

Determining Your Level of Access

In the future, apps will be able to determine the level of access they have to a user's data and the level of access the user has to their own data. Also, apps will be able to see the permissions that are included within an access token.

For each resource, an app will be able to see the level of permission (browse, read, create, and write) the app has to each resource. In addition, an app will be able to see the level of permission that the user has to each resource. This information will be included in the API responses for each of the Permissionable Resources described above.

For example, the GET: projects/{id} method's response would contain an additional field that shows the level of access the app has to the data and another field that shows the level of access the user has to the data.