Project Permissions and Sharing

Project permissions define the degree to which members can modify, create, and share project content, and whether they can change the project's members or owner.

A user or org may be granted access to a project at any of the following permission levels:

• NONE: Allows no access to a data container.

• VIEW: Allows read-only access to data objects and their metadata in a

  data container.

• UPLOAD: Allows "VIEW", plus the ability to create new folders and data objects, to modify the metadata of open data objects, and to close data objects. UPLOAD can also modify open files.

• CONTRIBUTE: Allows "UPLOAD", plus the ability to modify the contents of all types of data objects and to delete objects if the "PROTECTED" flag on the container is set to false.

• ADMINISTER: Allows "CONTRIBUTE", plus the ability to modify the member list and to modify or delete the data container.

A user is granted explicit permission to a project if the project is shared directly with the user. A user is granted implicit permission to a project if the project is shared with an org of which the user is an administrator or a member with appropriate organization permissions. Explicit and implicit project permissions are not mutually exclusive, and the actual permission level or access that a user has to a project is the GREATER of the two.

If you have ADMINISTER access to a project, then you can modify the list of users who can access the project by inviting users to particular permission levels (no action is taken if they already have the specified access level), or decreasing users' permissions to specified levels (potentially completely revoking all permissions, if desired).

If you do not have ADMINISTER access to a project, then you do not have any ability to modify the permission level of any other project member. However, you will always have the ability to leave the project.

Project Billing and Transfer

All storage and compute costs for a particular project are billed to a particular billing account (retrieved as the field billTo in the /project-xxxx/describe API method) . It is possible, however, to invite another user to take over the project's data and be the new billing account for the project. If the invitee accepts, the project is transferred over, and all job history is preserved. Note that any jobs that are launched before the transfer is accepted are still billed to the original billing account.

See the specifications below for more details.

API Method Specifications

API method: /project-xxxx/invite

Specification

Invites a DNAnexus user or org to the project at the specified permission level. An email address can be used to specify the invitee in the case of a user invitee. If the invitee already has access to the project but at a lower permission level than the one specified, then the permission level of the invitee will be upgraded to the specified permission level.

Inputs

• invitee string The entity that will receive access should the invite be accepted; must be a user or org ID, or an email address (email addresses will be resolved to a user, if possible)

• level string A permission level; must be one of "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER"

• suppressEmailNotification boolean (optional, default false) If true, then do not send an email notification to the invitee

Outputs

• id string or null Invite ID, or null if the invite did not need to be created (i.e. invitee already has at least the requested permission)

• state string State of the invite

Errors

• ResourceNotFound

  • invitee is not a valid email address, or is not an existing DNAnexus user or org

• InvalidInput

  • level is not provided OR level is not a valid permission level string

• PermissionDenied

  • Must have ADMINISTER access to the project, be the billTo with a full scope token (if the billTo is a user) , or be an admin of the billTo with a full scope token (if the billTo is an org)

  • Must have ADMINISTER access to the project to invite another user or org

API method: /project-xxxx/decreasePermissions

Specification

Decreases the requested permissions for the specified entities on the project. If the existing permissions for an entity are already at most as much as the requested permission level, then no change is made to that entity’s permissions. The existing permissions for entities not included in the input hash are not affected.

Inputs

• key A user or org ID for which the permission level should be decreased

• value string or null Permission level that the entity's access permissions to be decreased to, i.e. one of "VIEW", "UPLOAD", "CONTRIBUTE", and "ADMINISTER", or the value null to indicate that the entity's permissions should be revoked entirely

Outputs

• id string ID of the manipulated project

Errors

• ResourceNotFound (the specified project does not exist)

• InvalidInput

  • The input is not a hash

  • A value in the hash is neither the null value nor one of the allowed permission level strings "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER"

  • If a specified user is the billTo of the project, then the value corresponding to that user may only be "ADMINISTER"

• InvalidState (there is a pending transfer on the project, and the request would decrease the invitee's permissions to less than VIEW)

• PermissionDenied (ADMINISTER access required)

API method: /project-xxxx/leave

Specification

Renounces the requesting user’s access to the specified project. The user will no longer have access to the project unless the project is public. The billTo of a project, if a user, is not allowed to leave the project.

Inputs

• organization string (optional) ID of an org. If a string, then will leave the project on behalf of the organization (i.e. will revoke all project permissions granted to the organization)

Outputs

• id string ID of the manipulated project

Errors

• InvalidInput (the requesting user may not be the billTo of the project)

• ResourceNotFound (the specified project does not exist)

• PermissionDenied

  • A full scope token is required

  • If organization is specified, then the requesting user must be an administrator of that organization

API method: /project-xxxx/transfer

Specification

Invites another account to take over the billing for the project. In effect, this will change the billing account for the project and all associated containers (workspaces for running jobs, etc.) . If there are any jobs running at the time of transfer, their compute costs are still billed to the first billing account.

As a result of calling this API method, the invited account receives VIEW access (if necessary) , a notification is sent to the invited account holder, and the project enters a pending state. If the transfer is later cancelled before it is accepted, the invited account's permissions level to the project is reverted to the level that was held before this API method was called.

The transfer invitation can be cancelled at any time by calling this API method again with invitee set to null. Calling this API method with a different invitee will cancel any previous transfer invitations.

Invitees can see a list of pending transfer invitations by calling /user-xxxx/describe on themselves and providing the boolean flag pendingTransfers set to true.

Inputs

• invitee string or null email or user ID of the account to which to transfer the project's contents, or null to cancel a pending transfer

• suppressEmailNotification boolean (optional, default false) If true, do not send an email notification to the invitee

Outputs

• id string ID of the manipulated project

Errors

• InvalidInput (input is not a hash, invitee is not a string, suppressEmailNotification is provided but is not a boolean)

• ResourceNotFound (the specified project does not exist, the specified invitee does not exist as an account ID)

• PermissionDenied

  • Must have ADMINISTER access to the project, or be an ADMIN of the org that the project is billed to.

• InvalidState

  • invitee is already billed for the project

  • The project is sponsored (sponsorship must be terminated before attempting a transfer)

API method: /project-xxxx/acceptTransfer

Specification

Accept billing responsibility for the project, possibly on behalf of an org. Upon success, all storage charges, and compute charges for new jobs, will be charged to the new billing account, and the requesting user will be granted ADMINISTER permission to this project.

Inputs

• billTo string (optional, default is the billTo of the requesting user) billing account (user or org ID) that will be responsible for the project

Outputs

• id string ID of the manipulated project

Errors

• PermissionDenied

  • Cannot be invoked by a job

  • Must be the current invitee of the pending transfer for this project

  • If billTo is a user ID, then it must the the ID of the requesting user

  • If billTo is an org ID, then the requesting user must have allowBillableActivities permission in the org

  • If the project has the containsPHI flag set, the new billTo for the project must have the phiFeaturesEnabled flag set

  • If the project has the externalUploadRestricted flag set to true, the new billTo for the project must have the externalUploadRestrictedControl license feature

  • The requested billTo does not have this project's region as one of its permittedRegions