> For the complete documentation index, see [llms.txt](https://documentation.dnanexus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.dnanexus.com/getting-started/key-concepts/organizations.md). # Organizations {% hint style="info" %} This functionality is also available via command line interface (CLI) tools. You may find it easier to use the CLI tools to perform some actions, such as inviting multiple users or exporting information into a machine-readable format. {% endhint %} ## What Is an Org? An organization (or "org") is a DNAnexus entity used to manage a group of users. Use orgs to group users, projects, and other resources together, in a way that models real-world collaborative structures. In its simplest form, an org can be thought of as referring to a group of users on the same project. An org can be used efficiently to share projects and data with multiple users - and, if necessary, to revoke access. Org admins can manage org membership, configure access and projects associated with the org, and oversee billing. All storage and compute costs associated with an org are invoiced to a single billing account specified by the org admin. You can create an org that is associated with a billing account by contacting [DNAnexus Sales](mailto:sales@dnanexus.com). Orgs are referenced on the DNAnexus Platform by a unique org ID, such as `org-dnanexus`. Org IDs are used when sharing projects with an org in the Platform user interface or when manipulating the org in the CLI. {% embed url="" %} ## Org Membership Levels Users may have one of two membership levels in an org: * ADMIN * MEMBER An ADMIN-level user is granted all possible access in the org and may perform org administrative functions. These functions include adding and removing users, and modifying org policies. A MEMBER-level user, however, is granted only a subset of the possible org accesses in the org and has no administrative power in the org. ### Members A user with MEMBER level can be configured to have a subset of the following org access levels. These access levels determine which actions each user can perform in an org. | Access | Description | Options | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | **Billable activities access** | If allowed, the org member can create new projects and apps billed to the org, download data (incurring data egress charges against the org), and set their own default billing account to that of the org. | \[Allowed] or \[Not Allowed] | | **Shared apps access** | If allowed, the org member has access to view and run apps in which the org has been added as an "authorized user". | \[Allowed] or \[Not Allowed] | | **Shared projects access** | The maximum access level a user can have in projects shared with an org. For example, if this is set to UPLOAD for an org member, the member has at most UPLOAD access in projects shared with the org, even if the org was given CONTRIBUTE or ADMINISTER access to the project. | \[NONE], \[VIEW], \[UPLOAD], \[CONTRIBUTE] or \[ADMINISTER] | These accesses give you fine-grained control over what members of your org can do in the context of your org. ### Custom Role Permissions Besides the standard access levels, org admins can grant MEMBERs specific delegated capabilities through custom role permissions. These flags follow the principle of least privilege: MEMBERs only receive elevated capabilities explicitly granted to them by an org admin. Org ADMINs always have all custom role permissions implicitly. | Custom Role | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Archival Management** | Allows the member to archive and unarchive objects across all org projects, including using the `allCopies` flag, without being a project member. This delegates org-wide storage cost management without requiring org admin access. | | **Project Member Demotion** | Allows the member to decrease project member permissions on any org project without being a project member or project admin. The member can also audit another member's project access via [`/org-xxxx/findProjects`](/developer/api/organizations.md#api-method-org-xxxx-findprojects). | | **Data Deletion** | Allows the member to remove objects from any org project or container, bypassing project membership checks via the `overrideProjectAccess` flag. This delegates org-wide data cleanup without requiring org admin access. | | **Data Search** | Allows the member to list all copies of an object across the entire organization using `allCopiesForOrg`, even in projects where they are not members. This enables delegated org-wide data discovery and auditing. | Only org admins can grant or revoke custom role permissions. Members who hold a custom role permission cannot grant that same permission to other members. All operations performed using these delegated roles are recorded in the org audit log, regardless of whether the acting user is a project member. ### Admins Org admins are granted all possible access in the org. More specifically, org admins receive the following set of accesses: | Access | Level | | -------------------------- | ---------- | | Billable activities access | Allowed | | Shared apps access | Allowed | | Shared projects access | ADMINISTER | Org admins also have the following special privileges: #### Viewing Metadata for All Org Projects Org admins can list and view metadata for all org projects (projects billed to the org) even if the project is not explicitly shared with them. They can also give themselves access to any project billed to the org. For example, when a member creates a new project, Project-P, and bills it to the org, they are the only user with access to Project-P. The org admin can see all projects billed to the org, including Project-P. Org admins can also invite themselves to Project-P at any time to get access to objects and jobs in the project. #### Becoming a Developer for All Org Apps Org admins can add themselves as developers to any app billed to the org. For example, when a member creates a new app, App-A, billed to the org, they are the only developer for App-A. However, any org admins may add themselves as developers at any time. ## Examples of Using Orgs ### Org Structure Diagram In the diagram, there are 3 examples of how organizations can be structured. ![](/files/oQfakOoW2L7eqPN4C837) #### ORG-1 The simplest example, ORG-1, is represented by the leftmost circle. In this situation, ORG-1 is a billable org that has 3 members who share one billing account, so all 5 projects created by the members of ORG-1 are billed to that org. One admin (user A) manages ORG-1. #### ORG-2 and ORG-3 The second example shows a more complex organizational setup for ORG-2 and ORG-3. Here users are grouped into two different billable orgs, with some users belonging to both orgs and others belonging to only one. In this case, ORG-2 and ORG-3 bill their work against separate billing accounts. This separation of orgs can represent two different groups in one company working in different departments, each with their own budgets, two different labs that work together, or any other scenario in which two collaborators share work. ORG-2 has 5 members, 4 projects, and is managed by one org admin (user G). ORG-3 has 5 members and 3 projects, but is managed by 2 admins (users G and I). In this example, admin G and member H belong to both ORG-2 and ORG-3. They can create new projects billed to either org, depending on the project they're working on. Admin G can manage users and projects in both ORG-2 and ORG-3. ### Example 1: Creating an Org for Sharing Data You can create a non-billable org as an alias for a group of users. For example, you have a group of users who all need access to a shared dataset. You can make an org which represents all the users who need access to the dataset, for example, an org named `org-dataset_access`, and share all the projects and apps related to the dataset with that org. All members of the org have at least VIEW "shared project access" and "shared app access" so that they are all given permission to view the dataset. If a member no longer needs access to the dataset, they can be removed from the org, and then no longer have access to any projects or apps shared with `org-dataset_access`. ### Example 2: Only Admins can Create Projects You can contact [DNAnexus Sales](mailto:sales@dnanexus.com) to create a billable org where only one member, the org admin, can create new org projects. All other org members are not granted the "billable activities access", and so cannot create new org projects. The org admin can then assign each org member a "shared projects access" (VIEW, UPLOAD, CONTRIBUTE, ADMINISTER) and share every org project with the org with ADMINISTER access. The members' permissions to the projects are restricted by their respective "shared project access." For example, in a given group, bioinformaticians can be given CONTRIBUTE access to the projects shared with the entire org, so they can run analyses and produce new data in any of the org projects. However, the sequencing center technicians only need UPLOAD permissions to add new data to the projects. Analysts in the group are only given VIEW access to projects shared with the org. When you need to add a new member to your group and give them access to the projects shared with the org, you need to add them to the org as a new member and assign them the appropriate permission levels. This membership structure allows the org admin to control the number of projects billed to the org. The org admin can also share new projects with their org and revoke permissions from users who have been removed from the org. ### Example 3: Shared Billing Account You can contact [DNAnexus Sales](mailto:sales@dnanexus.com) to create a billable org where users work independently and bill their activities to the org billing account (as specified by the org admin). All org members are granted "billable activities access." The org members also need to share common resources. These resources might include incoming samples or reference datasets. In this case, grant all members "shared apps access" and assign VIEW as their "shared projects access." Store the reference datasets that need to be shared with the org in an "Org Resources" project that is shared with the org, which is granted VIEW access. The org can also have best-practice executables built as apps on the DNAnexus system. The apps can be shared with the org so all members of the org have access to these (possibly proprietary) executables. If any user leaves your company or institution, their access to reference datasets and executables is revoked by removing them from the org. ### Other Cases In general, it is possible to apply many different schemas to orgs as they were designed for many different real-life collaborative structures. If you have a type of collaboration you want to support, contact [DNAnexus Support](mailto:support@dnanexus.com) for more information about how orgs can work for you. ## Managing Your Orgs If you administer an org, see [Org Management](/admin/org-management.md) for step-by-step UI and CLI procedures. That page is the canonical home for org-admin tasks such as updating policies, managing members, reviewing org-billed projects, and handling billing and usage tasks. [Organization Member Guide](/user/organization-member-guide.md) covers tasks that org members perform for themselves, such as choosing an org as a default billing account, creating org-billed projects, or sharing resources with an org. ### Viewing and Updating Org Information The UI path to your org overview and settings is described in [Org Management](/admin/org-management.md#org-admin-guide). That page covers how to review organization IDs, member counts, linked projects, linked apps, and org admins. ### Managing Org Members [Org Management](/admin/org-management.md#edit-org-membership) covers how to invite members, update their access, and remove them from the org. For the meaning of standard access settings and delegated granular permissions, see [Org Membership Levels](#org-membership-levels). ### Inviting a New Member Org admins can invite existing DNAnexus users and assign both standard access settings and delegated custom role permissions. For the full UI and CLI flows, see [Edit Org Membership](/admin/org-management.md#edit-org-membership). If a user needs to set the org as their default billing account after you add them, see [Setting an Org as Your Default Billing Account](/user/organization-member-guide.md#setting-an-org-as-your-default-billing-account). #### Creating New DNAnexus Accounts Org admins can provision new DNAnexus accounts on behalf of the org when the org has the required license. For the full process, see [Provisioning New DNAnexus Accounts](/admin/org-management.md#provisioning-new-dnanexus-accounts). {% hint style="info" %} For information on a license that enables account provisioning, [contact DNAnexus Sales](mailto:sales@dnanexus.com). {% endhint %} ### Editing Member Access [Update Membership Access](/admin/org-management.md#update-membership-access) describes the full procedure, including bulk access updates and the UI and CLI paths for modifying existing members. Standard access settings are described in [Members](#members). Delegated granular permissions are described in [Custom Role Permissions](#custom-role-permissions). ### Removing Members [Remove a Member from an Org](/admin/org-management.md#remove-a-member-from-an-org) describes the UI and CLI steps. Removing a member revokes that user's access to projects and apps billed to or shared with the org. ## Org Projects For org-admin tasks such as listing all org projects or reviewing projects you do not belong to directly, see [Org Projects](/admin/org-management.md#org-projects). For member self-service project tasks, see [Creating a New Org Project](/user/organization-member-guide.md#creating-a-new-org-project) and [Transferring a Project to an Org](/user/organization-member-guide.md#transferring-a-project-to-an-org). ### Granting Admin Access to Org Projects [Grant Yourself Access to Org Projects](/admin/org-management.md#grant-yourself-access-to-org-projects) describes the org-admin steps to give yourself `ADMINISTER` access to an org-billed project. ## Org Billing [Org Billing and Finance](/admin/org-management.md#org-billing-and-finance) covers org-specific billing and usage guidance. [Billing](/admin/billing-and-account-management.md) covers billing setup mechanics, invoices, payment methods, and spending-limit administration. ### Accessing Org Billing Information To view billing details for an org, follow [Accessing Org Billing Information](/admin/org-management.md#accessing-org-billing-information). If you want to change your own default billing account to an org, see [Setting an Org as Your Default Billing Account](/user/organization-member-guide.md#setting-an-org-as-your-default-billing-account). ### Setting Up or Updating Billing Information for an Org [Setting up or Updating Billing Information for an Org](/admin/org-management.md#setting-up-or-updating-billing-information-for-an-org) describes the org-specific steps. For billing portal details, see [Setting Up Billing](/admin/billing-and-account-management.md#setting-up-billing). ### Setting and Modifying an Org Spending Limit [Request a Spending Limit Change for an Org](/admin/org-management.md#request-a-spending-limit-change-for-an-org) covers org-specific requests. For billing-account details about spending limits, see [Increasing Your Spending Limit](/admin/billing-and-account-management.md#increasing-your-spending-limit). ### Viewing Estimated Charges [Accessing Org Billing Information](/admin/org-management.md#accessing-org-billing-information) describes the billing summary steps and expected UI. ### Using Monthly Project Spending and Usage Limits {% hint style="info" %} You need a license to use both the *Monthly Project Spending Limit for Computing and Egress*, and *Monthly Project Spending Limit for Storage* features. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information. {% endhint %} For orgs with licensed monthly project compute, egress, or storage limits, org admins can configure default limits and enforcement actions for org-billed projects. For guidance, see [Configure Monthly Project Spending and Usage Limits](/admin/org-management.md#configure-monthly-project-spending-and-usage-limits). For billing mechanics, see [How Spending and Usage Limits Work](/admin/billing-and-account-management.md#how-spending-and-usage-limits-work). For the underlying policy fields, see [Org Policies](/developer/api/organizations.md#org-policies). If you manage these defaults through the API, use [API method: `/org/new`](/developer/api/organizations.md#api-method-org-new), [API method: `/org-xxxx/update`](/developer/api/organizations.md#api-method-org-xxxx-update), or [API method: `/org-xxxx/bulkUpdateProjectLimit`](/developer/api/organizations.md#api-method-org-xxxx-bulkupdateprojectlimit) to set limit values and related behaviors. Use [API method: `/org-xxxx/describe`](/developer/api/organizations.md#api-method-org-xxxx-describe) to retrieve the current configuration. ### Monitoring Spending and Usage {% hint style="info" %} Licenses are required to use the Per-Project Usage Report and Root Execution Stats Report features. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information. Configuration of these features, and report delivery, is handled by DNAnexus Support. {% endhint %} The Per-Project Usage Report and Root Execution Stats Report provide monthly breakdowns of charges incurred by org members. For report access, delivery, and usage details, see [Monitoring Account Spending and Usage](/admin/org-management.md#monitoring-account-spending-and-usage). ## Org Policies Org admins can also set configurable policies for the org. Org policies dictate many different behaviors when the org interacts with other entities. The following policies exist: | Policy | Description | Options | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | Membership List Visibility | Dictates the minimum org membership level required to view the list of org members, their membership level, and access within the org. If PUBLIC, any DNAnexus user can view the list of org members. | \[ADMIN], \[MEMBER], or \[PUBLIC] | | Project Transfer | Dictates the minimum org membership level allowed to change the billing account of an org project (via the UI or project transfer). | \[ADMIN] or \[MEMBER] | | Project Sharing | Dictates the minimum org membership level allowed for a user to invite that org to a project | \[ADMIN] or \[MEMBER] | | Instance Upgrade on Job Restart | Controls whether the platform automatically retries a job on a larger instance type when the job fails with an `AppInsufficientResourceError` (out of memory or out of storage). When enabled, the platform upgrades the instance one step within the same instance family on retry. This policy corresponds to the `allowInstanceUpgradeOnJobRestart` org policy key. | \[Enabled] or \[Disabled] (default: Disabled) | DNAnexus recommends, as a starting point, to restrict the "membership list visibility policy" to ADMIN and "project transfer policy" to ADMIN. This ensures that only the org admin is allowed to see the list of members and their access within the org and that org projects always remain under control of the org. You can update org policies for your org in the **Policies and Administration** section of the org **Settings** tab. Here, you can change the membership list visibility, restrict project transfer policies for the org, and contact DNAnexus Support to enable PHI data policies for org projects. ## Glossary of Org Terms * **Billable activities access** is an access level that can be granted to org members. If allowed, the org member can create new projects and apps billed to the org, download data (incurring data egress charges against the org), and set their own default billing account to that of the org. * **Billable org** is an org that has confirmed billing information or a non-negative spending limit remaining. Users with billable activities access in a billable org are allowed to create new projects billed to the org. See the definition of a non-billable org for an org that is used for sharing. * **Billed to an org** (app context) sets the billing account of an app to an org. Apps require storage for their resources and assets, and the billing account of the app is billed for that storage. The billing account of an app does not pay for invocations of the app unless the app is run in a project billed to the org. * **Billed to an org** (project context) sets the billing account of a project to an org. The org is invoiced for the storage for all data stored in the project as well as compute charges for all jobs and analyses run in the project. * **Custom role permission** is a delegated capability that an org admin can grant to an org MEMBER. The four custom role permissions are `archivalManagement`, `projectMemberDemotion`, `dataDeletion`, and `dataSearch`. Org ADMINs always have all custom role permissions. Members who hold a permission cannot grant it to other members. * **Membership level** describes one of two membership levels available to users in an org: ADMIN or MEMBER. Remember that ADMINISTER is a type of access level. * **Membership list** visibility policy dictates the minimum org membership level required to view the list of org members, their membership level, and access within the org. * **Non-billable org** describes an org only used as an alias for a group of users. Non-billable orgs do not have billing information and do not have any org projects or org apps. Any user can share a project with a non-billable org. * **Org access** is granted to a user to determine which actions the user can perform in an org. * **Org admin** describes administrators of an org who can manage org membership, configure access and projects associated with the org, and oversee billing. * **Org app** is an app billed to an org. * **Org ID** is the unique ID used to reference a particular org on the DNAnexus Platform. An example is `org-dnanexus`. * **Org member** is a DNAnexus user associated with an org. Org members can have variable membership levels in an org which define their role in the org. Admins are a type of org member as well. * **Org policy** is a configurable policy for the org. Org policies dictate many different behaviors when the org interacts with other entities. * **Org project** describes a project billed to an org. * **Org** (or "organization") is a DNAnexus entity that is used to associate a group of users. Orgs are referenced on the DNAnexus Platform by a unique org ID. * **Project transfer** policy dictates the minimum org membership level allowed to change the billing account of an org project. * **Share with an org** means to give the members of an org access to a project or app via giving the org access to the project or adding the org as an "authorized user" of an app. * **Shared apps access** is an org access level that can be granted to org members. If allowed, the org member can view and run apps in which the org has been added as an "authorized user." * **Shared projects access** is an org access level that can be granted to org members: the maximum access level a user can have in projects shared with an org. ## Learn More Learn in depth about [setting up and managing orgs as an administrator](/admin/org-management.md). Learn about [what you can do as an org member](/user/organization-member-guide.md). Learn about [creating and managing orgs as a developer, via the DNAnexus API](/developer/api/organizations.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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/getting-started/key-concepts/organizations.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.