# Project Permissions and Sharing 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](https://documentation.dnanexus.com/developer/api/organizations). **Explicit** and **implicit** project permissions are **not** mutually exclusive. 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. You can [invite](#api-method-project-xxxx-invite) users to particular permission levels (no action is taken if they already have the specified access level). You can also [decrease](#api-method-project-xxxx-decreasepermissions) users' permissions to specified levels (up to revoking all permissions). If you do not have ADMINISTER access to a project, you cannot modify the permission level of any other project member. However, you can still [leave](#api-method-project-xxxx-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`](https://documentation.dnanexus.com/developer/api/projects#api-method-project-xxxx-describe) API method). The [invite](#api-method-project-xxxx-invite) method allows another user to take over the project's data and become the new billing account for the project. When the invitee [accepts](#api-method-project-xxxx-accepttransfer), the project transfers, and all job history is preserved. Jobs launched *before* the transfer acceptance are 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, the permission level of the invitee is upgraded to the specified permission level. #### Inputs * `invitee` **string** (required) The entity to receive access when the invite is accepted. * Must be a user or org ID, or an email address (email addresses are resolved to a user, if possible). * `level` **string** (required) A permission level. * Must be one of `"VIEW"`, `"UPLOAD"`, `"CONTRIBUTE"`, or `"ADMINISTER"`. * `suppressEmailNotification` **boolean** (optional) If `true`, do not send an email notification to the invitee. Defaults to `false`. #### Outputs * `id` **string** (nullable) Invite ID, or `null` if the invite did not need to be created. This happens when the 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 * If the project is associated with a [TRE](https://documentation.dnanexus.com/developer/api/trusted-research-environments), the invitee must be the request owner or a collaborator on the data access request associated with the project. See [Non-Configurable Restrictions](https://documentation.dnanexus.com/developer/trusted-research-environments#non-configurable-restrictions). ### 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** (nullable) — the permission level to decrease the entity's access to, or `null` to revoke all permissions. * Must be one of `"VIEW"`, `"UPLOAD"`, `"CONTRIBUTE"`, `"ADMINISTER"`, or `null`. #### 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 loses access to the project unless the project is public. The `billTo` of a project, if a user, cannot leave the project. #### Inputs * `organization` **string** (optional) Organization ID. If provided, removes the organization from the project, revoking all permissions the organization has to the project. #### 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. This changes the billing account for the project and all associated containers (workspaces for running jobs, temporary storage, and child containers). For any jobs running during the transfer, compute costs remain billed to the first billing account. When called, this API method grants VIEW access to the invited account (if needed), sends a notification to the invited account holder, and puts the project in a pending state. If the transfer is cancelled before acceptance, the invited account's permissions level reverts to its previous level. Cancel the transfer invitation by calling this API method with `invitee` set to `null`. Calling this API method with a different invitee cancels any previous transfer invitations. Invitees see a list of pending transfer invitations by calling [`/user-xxxx/describe`](https://documentation.dnanexus.com/developer/users#api-method-user-xxxx-describe) on themselves and providing the boolean flag `pendingTransfers` set to true. #### Inputs * `invitee` **string** (required, nullable) 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) If `true`, do not send an email notification to the invitee. Defaults to `false`. #### 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) * The project is associated with a [TRE](https://documentation.dnanexus.com/developer/api/trusted-research-environments). Transferring TRE projects is not allowed. See [Non-Configurable Restrictions](https://documentation.dnanexus.com/developer/trusted-research-environments#non-configurable-restrictions). ### API method: `/project-xxxx/acceptTransfer` #### Specification Accept billing responsibility for the project, possibly on behalf of an org. On success, all storage charges and compute charges for new jobs are charged to the new billing account, and the requesting user receives ADMINISTER permission to this project. #### Inputs * `billTo` **string** (optional) Billing account (user or org ID) to be responsible for the project. Defaults to the `billTo` of the requesting user. #### 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 be 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 * If the project has the `httpsAppIsolatedBrowsing` flag set to `true`, the new `billTo` for the project must have the `httpsAppIsolatedBrowsingControl` license feature * The requested `billTo` does not have this project's `region` as one of its `permittedRegions` * Can not change the billTo of project-xxxx while the project contains a [DBCluster](https://documentation.dnanexus.com/developer/api/introduction-to-data-object-classes/dbclusters) * InvalidState * The project is associated with a [TRE](https://documentation.dnanexus.com/developer/api/trusted-research-environments). Accepting transfers for TRE projects is not allowed. See [Non-Configurable Restrictions](https://documentation.dnanexus.com/developer/trusted-research-environments#non-configurable-restrictions). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.dnanexus.com/developer/api/data-containers/project-permissions-and-sharing.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.