# Organizations

An organization (or org) is a DNAnexus entity that associates a group of users. The administrators of an org manage account creation, configure permissions in the context of the org as well as the projects owned by the org, and oversee billing. All storage and compute costs associated with an org are invoiced to a single billing account chosen by the org administrators. Data objects and projects can be shared with orgs as an entity.

## Org Membership Status

A user may be a member of an org at one of two membership statuses:

1. ADMIN
2. MEMBER

An org ADMIN is granted all standard org permissions and may perform org administrative functions such as adding or removing users, or modifying org policies. The `treManagement` permission is configured independently for both ADMINs and MEMBERs. An org MEMBER, however, is granted only a subset of the possible permissions in the org and does not have standard org-admin capabilities such as user management or org policy changes, though the user may still have `treManagement`.

## Org Permission Flags

Org permission flags, configurable by user, specify the allowable actions for each user in an org. The following permission flags exist:

* `allowBillableActivities` **boolean** Whether the user can perform certain activities that would incur charges for the org. Users with this flag set to true may create projects and apps billed to the org and download files while billing the data transfer costs to the org. They may also view the org's pricing model (and view the cost of any projects or jobs billed to the org).
* `projectAccess` **string** The maximum project permission granted to the user for projects shared with the org.
  * Must be one of `"ADMINISTER"`, `"CONTRIBUTE"`, `"UPLOAD"`, `"VIEW"`, or `"NONE"`.
* `appAccess` **boolean** Whether the user can access and run apps shared with the org.
* `treManagement` **boolean** Whether the user can create and manage [Trusted Research Environments (TREs)](https://documentation.dnanexus.com/developer/api/trusted-research-environments) for the org. This flag is independent of the user's membership level (ADMIN or MEMBER). In the UI, this permission appears as **Research Environment Management**.

Org ADMINs have all available org permissions except `treManagement`, which is set independently.

```json
{
  "allowBillableActivities": true,
  "projectAccess": "ADMINISTER",
  "appAccess": true
}
```

Org MEMBERs, by default, receive the following set of permission flags:

```json
{
  "allowBillableActivities": false,
  "projectAccess": "CONTRIBUTE",
  "appAccess": true
}
```

Any org ADMIN can configure the permission flags for org MEMBERs using [`/org-xxxx/setMemberAccess`](#api-method-org-xxxx-setmemberaccess). Org ADMINs with `treManagement` can also set `treManagement` for ADMINs and MEMBERs.

## Org Policies

Org policies, configurable by org, dictate many different behaviors when the org interacts with other entities. The following policies exist:

* `memberListVisibility` **string** (default `"ADMIN"` in [`/org/new`](#api-method-org-new)) The org membership status required to be able to view the membership status and permission flags in effect for any other member of the org (via [`/org-xxxx/findMembers`](#api-method-org-xxxx-findmembers)). Must be one of `"ADMIN"`, `"MEMBER"`, or `"PUBLIC"`. If `"PUBLIC"`, then any DNAnexus user may view the membership status and permission flags in effect for any member of the org.
* `restrictProjectTransfer` **string** (default `"MEMBER"` in `/org/new`) The org membership status required to change the billing account of a project billed to this org. Must be one of `"ADMIN"` or `"MEMBER"`. If `"ADMIN"`, only org ADMINs can change the billing account of an org-billed project. If `"MEMBER"`, any org member can do so.
* `restrictProjectSharing` **string** (default "MEMBER" in `/org/new`) The org membership status required to invite the org to be a member of a project. If set to "MEMBER" any member of the org can invite the org to a project. When set to "ADMIN", only org admins can invite the org to a project.
* `jobReuse` **boolean** (default `false` in `/org/new`) Enables reuse of outputs from jobs that share the same executable and input IDs. For more information, see [Smart Reuse](https://documentation.dnanexus.com/user/running-apps-and-workflows/job-reuse). This feature is only available for licensed customers.
* `detailedJobMetricsCollectDefault` **boolean** (default `false` in `/org/new`) If set to true, more frequent, detailed job metrics (tracking CPU, memory, network, disk, etc) are collected by default for all jobs launched in all projects billed to this org. This setting can be overridden when launching an execution. This field is only applicable to orgs with a `detailedJobMetrics` license.
* `allowInstanceUpgradeOnJobRestart` **boolean** (default `false` in `/org/new`) Controls whether the platform automatically retries a job on a larger instance type when the job fails with [`AppInsufficientResourceError`](https://documentation.dnanexus.com/apps/error-information#appinsufficientresourceerror) (out of memory or out of storage).
  * When set to `true` and a job restart is triggered, the platform upgrades the instance one step within the same instance family (based on the system instance upgrade mapping).
  * When set to `false` (the default) and a job restart is triggered, `AppInsufficientResourceError` behaves like `AppInternalError`, the platform reuses the original instance (no instance upgrade occurs).
  * `AppInsufficientResourceError` inherits the `AppInternalError` restart counts. If a `restartOn` policy for `AppInsufficientResourceError` is not specified in the executable's execution policy or in the job's runtime configuration, but a `restartOn` policy for `AppInternalError` is specified, `AppInsufficientResourceError` uses the existing `AppInternalError` `restartOn` policy.
* `maximumPreauthenticatedDuration` **integer** (optional) Maximum number of seconds that a preauthenticated file download URL is valid for. If set to 0, preauthenticated URLs are disabled for the whole organization. Defaults to `43200` (12 hours). Must be no more than `86400` (24 hours).
  * The security of preauthenticated URLs (also known as a pre-signed URL) is the responsibility of the client. DNAnexus does not revoke preauthenticated URLs once generated. Take care with longer-lived URLs, as they remain valid for their full duration.
  * Setting `maximumPreauthenticatedDuration` below a minimum threshold of 300 seconds (5 minutes) can cause dependent functionality to break. For example, File Viewers and some automated tools require URLs to be valid for 3-5 minutes to complete downloads or viewing sessions. Ensure the duration meets all intended use cases.

{% hint style="info" %}
A license is required to set the following Monthly Project Spending Limit for Computing and Egress policies. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

* `monthlyProjectComputeLimitDefault` **integer** (optional, nullable) Default dollar values of project level spending limits for compute in currency. This limit does not apply to DBCluster-related charges. Defaults to `null` in `/org/new`.
* `monthlyProjectEgressBytesLimitDefault` **integer** (optional, nullable) Default values of project level spending limits for egress in bytes. Defaults to `null` in `/org/new`.
* `monthlyProjectStorageLimitDefault` **number** (optional, nullable) Default dollar values of project level spending limits for storage in currency. This limit does not apply to DBCluster-related charges. Defaults to `null` in `/org/new`.
* `enforceTerminationForProjectComputeLimit` **boolean** (optional) Whether the system should enforce termination behaviors when the project compute spending limit is exceeded. Defaults to `false` in `/org/new`.
* `enforceTerminationForProjectEgressBytesLimit` **boolean** (optional) Whether the system should enforce termination behaviors when the project egress spending limit is exceeded. Defaults to `false` in `/org/new`.
* `enforceTerminationForProjectStorageLimit` **boolean** (optional) Whether the system should enforce termination behaviors when the project storage spending limit is exceeded. Not Changeable. Defaults to `false` in `/org/new`.
* `projectSpendingLimitNotificationThreshold` **integer** (optional) Percent threshold for sending out the warning notification for the monthly project spending budget. When the available monthly project spending budget drops below the threshold, the system sends email notifications to the admins of the affected project. Defaults to `90` in `/org/new`. Must be between 1 and 99.

## API Method Specifications

### API Method: `/org/new`

#### Specification

Creates a new non-billable organization. After creation, the requesting user receives sole ADMIN rights of the organization. The organization's handle and name remain visible to the public. The org functions as an [alias for a group of users](https://documentation.dnanexus.com/getting-started/key-concepts/organizations#example-1-creating-an-org-for-sharing-data), but does not allow billable activities (such as creation of projects or uploading of data). Contact [DNAnexus Sales](mailto:sales@dnanexus.com) to create a billable org.

#### Inputs

* `handle` **string** (required) A case-insensitive unique handle for the org. The chosen handle must **not** exist in use by any other user or org. The lowercase of `handle` appends to "org-" to form the ID of this org. An org handle:
  * must start with an alpha character (uppercase or lowercase)
  * must be at least 3 characters long
  * may contain alphanumeric characters (uppercase and lowercase), periods, and underscores
  * must be no longer than 33 characters
* `name` **string** (required) A descriptive name for the organization.
* `policies` **mapping** (optional) A set of organization policies to override the corresponding default policies. Policies that are not included inherit the system default policies. See [org policies](#org-policies) for more information.
* `nonce` **string** (optional) Unique identifier for this request. Ensures that even if multiple requests fail and are retried, only a single org is created. For more information, see [Nonces](https://documentation.dnanexus.com/developer/api/nonces).

#### Outputs

* `id` **string** ID of the newly created organization ("org-" + `handle`).

#### Errors

* InvalidInput
  * A `nonce` was reused in a request but other inputs had changed signifying a new and different request
  * A `nonce` may not exceed 128 bytes
* InvalidState
  * The `handle` of the org case-insensitively matches that of an existing org or user, or of a previously destroyed org
* PermissionDenied
  * The requesting user does not have a full scope token
  * User cannot set the following `policies`:
    * `monthlyProjectComputeLimitDefault`
    * `monthlyProjectEgressBytesLimitDefault`
    * `monthlyProjectStorageLimitDefault`
    * `enforceTerminationForProjectComputeLimit`
    * `enforceTerminationForProjectEgressBytesLimit`
    * `enforceTerminationForProjectStorageLimit`
    * `projectSpendingLimitNotificationThreshold`

{% hint style="info" %}
Licenses are required 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 %}

### API Method: `/org-xxxx/describe`

#### Specification

Describes an organization. The output may be restricted if this is invoked by a non-member user. The exact subset of fields that is returned is defined by the organization's policies.

#### Inputs

* `defaultFields` **boolean** (optional) Includes the default set of fields in the output (see "Outputs" section). Fields named explicitly in `fields` override these selections.
  * Defaults to `false` if `fields` is provided, `true` otherwise.
* `fields` **mapping** (optional) Specifies fields to include or exclude from the output. These selections override `defaultFields` settings.
  * **key** — Output field to include or exclude (see the "Outputs" section below for valid values).
  * **value** **boolean** — Whether to include the field.

The following options are deprecated (and are not respected if `fields` is present):

* `pendingTransfers` **boolean** (optional) If true, returns a list of project IDs which the org has been invited to be the billing account for. Defaults to `false`.

#### Outputs

* `id` **string** The organization ID.

The following fields are included by default (but can be disabled using `fields` or `defaultFields`):

* `class` **string** The string "org".
* `handle` **string** The organization handle, as originally provided to [`/org/new`](#api-method-org-new).
* `name` **string** The descriptive name of the organization.
* `tre` **mapping** TRE association details. Only present when the org is associated with a [Trusted Research Environment](https://documentation.dnanexus.com/developer/api/trusted-research-environments).
  * `treId` **string** ID of the TRE.

The following field (included by default) is available if the org's memberListVisibility policy is set to 'PUBLIC', or if the policy is any other value and the requesting user is a MEMBER of the org with a full-scope token.

* `admins` **array of strings** The IDs of users who are ADMINs of the organization.

**The remaining keys are only available if a full scope token is supplied**.

The following fields (included by default) are available if the requesting user is a member of the org:

* `level` **string** Membership level of the requesting user in the org.
* `allowBillableActivities` **boolean** Whether the requesting user can perform billable activities on behalf of the org (see [Organization permission flags](#org-permission-flags) for more information).
* `projectAccess` **string** The maximum project permission the requesting user is granted via the org to projects explicitly shared with the org (see [Organization permission flags](#org-permission-flags) for more information).
* `appAccess` **boolean** Whether the requesting user can access and run apps shared with the org (see [Organization permission flags](#org-permission-flags) for more information).
* `treManagement` **boolean** Whether the requesting user can create and manage Trusted Research Environments (TREs) for the org (see [Organization permission flags](#org-permission-flags) for more information).
* `policies` **mapping** Organization-wide policies.
* `pendingBillingInformation` **mapping** (nullable) A mapping containing billing information that goes into effect once the accounts payable contact agrees to and confirms the billing information, or `null` if there is no pending billing information.
* `estSpendingLimitLeft` **number** (nullable) The estimated number of dollars remaining before new activities billed to the org are locked down. A value of `null` indicates that no spending limit is imposed on the account. This value may be negative, which indicates that the org has exceeded the spending limit. The value may continue to decrease if jobs are still running or if projects with nonzero storage amounts are still billed to the org.
* `phiFeaturesEnabled` **boolean** Whether PHI features have been enabled for the account.
* `defaultRegion` **string** The default region in which newly created projects billed to this org reside (may be overridden at project creation time). For more information about regions, see [Regions](https://documentation.dnanexus.com/developer/api/regions).
* `permittedRegions` **array of strings** The regions in which this org can create projects. For more information about regions, see [Regions](https://documentation.dnanexus.com/developer/api/regions).

The following fields (included by default) are available if the requesting user is a MEMBER of the org and billing information has been confirmed for this billing account:

* `billingInformation` **mapping** The confirmed billing contact information to which invoices are sent.

The following fields (included by default) are available if the requesting user is a member of the org with `allowBillableActivities` permission:

* `computeCharges` **number** Running total of compute charges (in dollars) for the account.
* `computeChargesReflectedUntil` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Last date for which `computeCharges` were calculated.
* `computeChargesComputedAt` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time when `computeCharges` were updated in the system.
* `storageCharges` **number** Running total of storage charges (in dollars) for the account.
* `storageChargesReflectedUntil` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Last date for which `storageCharges` were calculated.
* `storageChargesComputedAt` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time that `storageCharges` were last updated in the system.
* `dataEgressCharges` **number** Running total of data egress charges (in dollars) for the account.
* `dataEgressChargesReflectedUntil` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Last date for which `dataEgressCharges` were calculated.
* `dataEgressChargesComputedAt` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time that `dataEgressCharges` were last updated in the system.
* `dearchivalCharges` **number** Running total of data dearchival charges (in dollars) for the account.
* `dearchivalChargesReflectedUntil` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Last date for which `dearchivalCharges` were calculated.
* `dearchivalChargesComputedAt` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time that `dearchivalCharges` were last updated in the system.
* `dbclusterCharges` **number** Running total of DB cluster charges (in dollars) for the account.
* `dbclusterChargesReflectedUntil` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Last date for which `dbclusterCharges` were calculated.
* `dbclusterChargesComputedAt` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time that `dbclusterCharges` were last updated in the system.

The following fields are only returned if the corresponding field in the `fields` input is set to true, the user is a member of the org with `allowBillableActivities` permission, and billing information has been confirmed for this billing account:

* `pricingModelsByRegion` **mapping** Contains information about the pricing models that are in effect for the org (applied to projects whose `billTo` is this org). This mapping has one entry for each region in the `permittedRegions` of the org:
  * **key** — The region ID (for example, `aws:us-east-1`).
  * **value** **mapping** — The pricing model that is applied in this region:

    * `storageRatePerGBMonth` **number** Storage rate (in dollars per GB-month) for ordinary (non-archival) storage in this region.
    * `computeRatesPerHour` **mapping** Contains compute rates for each instance type the account can use in this region. For a list of available instance types, see: [Instance Types](https://documentation.dnanexus.com/developer/api/running-analyses/instance-types).
      * **key** — Instance type name.
      * **value** **number** — Rate (in dollars per instance-hour).
    * `ipRates` **mapping** Rate for data leaving DNAnexus from this region to specific destination IP ranges (specified in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)). If an IP is in more than one specified range, the rate is given by the most specific matching IP range. The mapping includes the predefined key "0.0.0.0/0" with the default rate.
      * **key** — IP range (specified in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)).
      * **value** **number** — Rate (in dollars per GB) leaving DNAnexus to that IP range.
    * `publicIPv4AddressRatePerHour` **number** Per-hour charge (in currency units) for using IPv4 addresses for workers in this region.

    The following field is present **only** if the org has the `phiFeaturesEnabled` field set to true:
  * `computeRatesPerHourPHI` **mapping** Contains compute rates for each instance type the account can use in this region, applied only to projects that have the `containsPHI` flag set.
    * **key** — Instance type name.
    * **value** **number** — Rate (in dollars per instance-hour) for this instance type.

The following fields are present only if the org has the [Relational Database Service](https://documentation.dnanexus.com/user/objects/relational-database-clusters) enabled:

* `dbclusterStorageRatePerGBMonth` **number** Storage rate (in dollars per GB-month) for storage used by DBCluster, in this region.
* `dbclusterBackupPerGBMonth` **number** Backup storage rate (in dollars per GB-month) for storage used by DBCluster, in this region.
* `dbclusterIORequestsPer1M` **number** The rate (in dollars) charged per million of I/O requests made to the DBCluster billed to this org. See [AWS Aurora FAQ on I/O operations](https://aws.amazon.com/rds/aurora/faqs/) for more details.
* `dbclusterInstanceRatesPerHour` **mapping** Contains compute rates (in dollars) for each instance type used for DBCluster, that the account can use in this region.
* `dbclusterInstanceCpuBurstRatesPerHour` **mapping** Contains CPU Burst rates (in dollars) for each bursting DBCluster instance type that the account can use in this region. db\_std1 instances may incur CPU Burst charges similar to AWS T3 Db instances described in [AWS RDS instance types documentation](https://aws.amazon.com/rds/instance-types/). `db_std1_x1` has 2 cores. Regular hourly charges for this instance type are based on 1 core, CPU Burst charges are based on 2 cores.

The following fields are only returned if the corresponding field in the `fields` input is set to true and the requesting user is an ADMIN of the org:

* `expiresAt` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) The date when the organization expires and all associated data is permanently deleted. Organization expiration dates are typically set for temporary organizations.
  * Only present when the organization has an expiration date.
* `pendingTransfers` **array of strings** List of project IDs which the org has been invited to be the billing account for.
* `userCreationFeaturesEnabled` **boolean** Whether ADMINs of this org may provision a new account for another user.

{% hint style="info" %}
A license is required to enable org admins to provision accounts for other users. Contact [DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

The following fields are only returned if the requesting user is an ADMIN of the org:

* `auditLogProjectId` **string** The ID of the project that stores audit logs.
  * Only present when [Audit Trail](https://documentation.dnanexus.com/admin/audit-trail) is enabled for the org.
* `monthlyReportsProjectId` **string** The ID of the project that stores monthly project usage reports.
  * Only present when [Per-Project Usage Report](https://documentation.dnanexus.com/admin/org-management#per-project-usage-report) is enabled for the org.
* `usageReportingPolicies` **mapping** Configuration for monthly project usage reports. Contains the following key:
  * Only present when the `detailedUsageReportProjectLevel` feature is enabled for the org.
  * `projectId` **string** The ID of the project where monthly project-level usage reports are delivered.
* `jobLogsForwarding` **mapping** Job logs forwarding settings for the org, or `null` if job logs forwarding has not been configured for the org or if the org does not have a job logs forwarding license. This mapping may contain the following keys:
  * `url` **string** The URL of the Splunk endpoint.
    * Only present when the org is configured to send job logs to Splunk.
  * `tokenSignature` **string** The sha256 of the Splunk token supplied to `/org-xxxx/update`.
    * Only present when the org is configured to send job logs to Splunk.
  * `updated` **integer** The timestamp when this configuration was last updated.
  * `updatedBy` **string** The user id that issued the last configuration update.

{% hint style="info" %}
A license is required to use the [Forwarding Job Logs to customer's Splunk](https://documentation.dnanexus.com/admin/org-management#forwarding-job-logs-to-customers-splunk) feature. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

The following keys in `policies` (included by default) are available if the requesting user is a member of the org and if the org has the Monthly Project Spending Limit feature enabled:

* `monthlyProjectComputeLimitDefault` (see [Org Policies](#org-policies) for details)
* `monthlyProjectEgressBytesLimitDefault` (see [Org Policies](#org-policies) for details)
* `monthlyProjectStorageLimitDefault` (see [Org Policies](#org-policies) for details)
* `enforceTerminationForProjectComputeLimit` (see [Org Policies](#org-policies) for details)
* `enforceTerminationForProjectEgressBytesLimit` (see [Org Policies](#org-policies) for details)
* `enforceTerminationForProjectStorageLimit` (see [Org Policies](#org-policies) for details)
* `projectSpendingLimitNotificationThreshold` (see [Org Policies](#org-policies) for details)

{% hint style="info" %}
A license is required to use the Monthly Project Spending Limit for Storage feature. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

#### Errors

* PermissionDenied
  * `jobLogsForwarding` field can only be explicitly requested by an org ADMIN with a full scope token

### API Method: `/org-xxxx/update`

#### Specification

Updates information about an organization. The requesting user must be an ADMIN of the organization.

#### Inputs

* `name` **string** (optional) A descriptive name for the organization.
* `policies` **mapping** (optional) A set of organization policies to override the existing policies. Policies that are not included in the mapping are not updated. See [org policies](#org-policies) for more information.
* `defaultRegion` **string** (optional) The default region in which all newly created projects billed to this org reside (may be overridden at project creation time). For more information about regions, see [Regions](https://documentation.dnanexus.com/developer/api/regions).
* `jobLogsForwarding` **mapping** (optional) Configuration to enable or disable the forwarding of job logs billed to this org to a customer's Splunk instance. See [Forwarding Job Logs to customer's Splunk](https://documentation.dnanexus.com/admin/org-management#forwarding-job-logs-to-customers-splunk) for more information. Supplying an empty mapping disables job logs forwarding. If job logs forwarding is already disabled, the operation succeeds without updating the org's `jobLogsForwarding` configuration. Otherwise, the mapping requires the following keys:
  * `url` **string** (required) The URL of the Splunk HEC endpoint to receive forwarded job logs. Must start with `"https://"`. For example: `https://http-inputs-examplecompany.splunkcloud.com/services/collector/event`
  * `token` **string** (required) The Splunk HEC token string for forwarding job logs to Splunk.

    Enabling job logs forwarding prints the following message to the configured Splunk instance:\
    \
    `user-xxxx, an admin of org-yyyy is enabling DNAnexus job logs forwarding with these parameters`\
    `{"url": "<url>","tokenSignature": "<sha256OfSplunkToken>"}`

{% hint style="info" %}
A license is required to use the [Forwarding Job Logs to Customer's Splunk](https://documentation.dnanexus.com/admin/org-management#forwarding-job-logs-to-customers-splunk) feature. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

#### Outputs

* `id` **string** ID of the organization.

#### Errors

* InvalidInput
  * `defaultRegion` is not in the org's `permittedRegions`.
  * If `monthlyProjectComputeLimitDefault` in `policies` is not an integer and not `null`, or not larger than zero.
  * If `monthlyProjectEgressBytesLimitDefault` in `policies` is not an integer and not `null`, or not larger than zero.
  * If `monthlyProjectStorageLimitDefault` in `policies` is not a number and not `null`, or not larger than zero.
  * If `enforceTerminationForProjectComputeLimit` in `policies` is not a boolean.
  * If `enforceTerminationForProjectEgressBytesLimit` in `policies` is not a boolean.
  * If `projectSpendingLimitNotificationThreshold` in `policies` is not an integer, or not a value between 1 and 99.
  * `detailedJobMetricsCollectDefault` in `policies` input must be a boolean.
  * `jobLogsForwarding.url` must start with `https://`.
  * `jobLogsForwarding.url` must not exceed 1024 characters.
  * `jobLogsForwarding` must be an empty hash or a hash with `jobLogsForwarding.url` and `jobLogsForwarding.token` fields.
  * Attempt to upload to `<Splunk HEC URL>` failed with `<Splunk upload error code> '<Splunk upload error message>'`.
  * `jobLogsForwarding` cannot be updated together with other org attributes.
* InvalidState
  * The organization has reached the maximum number of members allowed. Applicable only to orgs with [Omics Data Catalog](https://documentation.dnanexus.com/user/omics-data-catalog) enabled.
* PermissionDenied
  * The requesting user is not an ADMIN of the organization.
  * The requesting user does not have a full scope token.
  * If `monthlyProjectSpendingLimit` is not enabled for the org but the following fields are provided for `policies`:
    * `monthlyProjectComputeLimitDefault`
    * `monthlyProjectEgressBytesLimitDefault`
    * `enforceTerminationForProjectComputeLimit`
    * `enforceTerminationForProjectEgressBytesLimit`
    * `projectSpendingLimitNotificationThreshold`
  * If `monthlyProjectStorageSpendingLimit` is not enabled for the org,

    the following fields are provided for `policies`:

    * `monthlyProjectStorageLimitDefault`
  * If the Detailed Job Metrics feature is not enabled for the org, the following fields are provided for `policies`:
    * `detailedJobMetricsCollectDefault`
  * If the Job Logs Forwarding feature is not enabled for the org, but the following fields are provided:
    * `jobLogsForwarding`

{% hint style="info" %}
Licenses are required to use the Monthly Project Spending Limit for Computing and Egress, Monthly Project Spending Limit for Storage, and Job Logs Forwarding features. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

### API Method: `/org-xxxx/invite`

#### Specification

Invites a user to become a member of the organization. Sends the invitation to an existing user or email address.

#### Inputs

* `invitee` **string** (required) User ID or email address of the user that is invited to the organization with a membership status of `level`.
* `treManagement` **boolean** (optional) If true, grants the invitee the `treManagement` permission flag. This flag can be set for both ADMIN and MEMBER levels. Defaults to `false`.
* `level` **string** (optional) Membership status that the invitee receives. Defaults to `"MEMBER"`.
  * Must be one of `"MEMBER"` or `"ADMIN"`.
* `message` **string** (optional) A message to the recipient `invitee`.
* `suppressEmailNotification` **boolean** (optional) If true, does not send an email notification to the `invitee`. Defaults to `false`.

If `level` is "MEMBER", then the following optional org permission flags (see [Org Permission Flags](#org-permission-flags) for more information) may be included:

* `allowBillableActivities` **boolean** (optional) Whether the `invitee` can perform billable activities on behalf of the org. Defaults to `false`.
* `appAccess` **boolean** (optional) Whether the user can access and run apps shared with the org. Defaults to `true`.
* `projectAccess` **string** (optional) The maximum project permission the `invitee` is granted via the org to projects explicitly shared with the org. Defaults to `"CONTRIBUTE"`.
  * Must be one of `"ADMINISTER"`, `"CONTRIBUTE"`, `"UPLOAD"`, `"VIEW"`, or `"NONE"`.

#### Outputs

* `id` **string** 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 an existing user or is not a valid email address
* InvalidState
  * The organization has reached the maximum number of members allowed. Applicable only to orgs with [Omics Data Catalog](https://documentation.dnanexus.com/user/omics-data-catalog) enabled.
* PermissionDenied
  * The requesting user is not an ADMIN of the organization
  * The requesting user does not have a full scope token.
  * The requesting user does not have the `treManagement` permission but attempted to set `treManagement` to `true` for the invitee

### API Method: `/org-xxxx/setMemberAccess`

#### Specification

Modifies the organization [membership statuses](#org-membership-status) and/or [permission flags](#org-permission-flags) for members of the organization. To add new users to the organization, refer to [`/org-xxxx/invite`](#api-method-org-xxxx-invite).

Changes in user membership status from "ADMIN" to "MEMBER" require specifying permission flags.

For an existing user who is a "MEMBER" and remains a "MEMBER", the specified permission flags are set, and those that are unspecified are unaffected.

When changing a user's membership status from "MEMBER" to "ADMIN", permission flags other than `treManagement` cannot be specified.

This method attempts to make all possible modifications. If some modifications fail because users in the input are not members of the organization, the method applies changes to all remaining users **and** throws an InvalidState error. This behavior does **not** apply to other errors.

#### Inputs

* The input to `/org-xxxx/setMemberAccess` is a mapping with the following key-value pairs:
  * **key** — User ID.
  * **value** **mapping** — A mapping of organization membership status and permission flags to set for the corresponding user. Includes the following key-value pairs:
    * `treManagement` **boolean** (optional) Whether the corresponding user can create and manage TREs for the org. This flag is independent of the ADMIN or MEMBER level.
    * `level` **string** The membership status to set for the user. The following fields are **required** if `level` is "MEMBER" and the corresponding user has a membership status of "ADMIN", **prohibited** if `level` is "ADMIN" (except `treManagement`), and optional otherwise:
      * Must be one of `"MEMBER"` or `"ADMIN"`.
    * `allowBillableActivities` **boolean** (optional) Whether the corresponding user can perform billable activities on behalf of the org.
    * `appAccess` **boolean** (optional) Whether the corresponding user can access or run apps shared with the org.
    * `projectAccess` **string** (optional) The maximum project permission the corresponding user is granted via the org to projects explicitly shared with the org.
      * Must be one of `"ADMINISTER"`, `"CONTRIBUTE"`, `"UPLOAD"`, `"VIEW"`, or `"NONE"`.

#### Outputs

* `id` **string** ID of the organization.

#### Errors

* InvalidInput
  * The requesting user specified themselves in the input
  * `treManagement` is provided but is not a boolean
* InvalidState
  * At least one of the users is neither a MEMBER nor an ADMIN of the organization
* PermissionDenied
  * The requesting user is not an ADMIN of the organization
  * The requesting user does not have a full scope token
  * The requesting user does not have the `treManagement` permission but attempted to set `treManagement` to `true` for the specified user ID

### API Method: `/org-xxxx/findProjects`

#### Specification

Lists projects that are billed to the org (and optionally describes those projects). Only ADMINs of the org are allowed to perform this operation.

Projects are ordered by:

* Last modified time stamp (descending), then
* ID (ascending)

This behaves similarly to [`/system/findProjects`](https://documentation.dnanexus.com/developer/search#api-method-system-findprojects)

#### Inputs

* `name` **string or mapping** (optional) If a string, then the exact case-sensitive name that the resulting projects must have. If a mapping, then may include any subset of the following key-value pairs:
  * `regexp` **string** (mutually exclusive with `glob`, required if `glob` is not present) A [PCRE](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions) regular expression that must be matched by the name of all resulting projects.
  * `flags` **string** (optional if `regexp` is present, prohibited otherwise) This field can only have value `"i"` to enable case-insensitive matching for the regular expression.
  * `glob` **string** (mutually exclusive with `regexp`, required if `regexp` is not present) A wildcard pattern that must be matched by the name of all resulting projects. The valid wildcard patterns are `'*'` (0 or more characters) and '?' (1 character).
* `id` **array of strings** (optional) If specified, the resulting projects must have project IDs among this list of IDs. The array may contain no more than 1000 elements.
* `tags` **string or mapping** (optional) Specifies the tags that all resulting projects must have. Can be provided in the following ways:
  * A string to match a single tag exactly, for example, `"production"`.
  * An AND condition requiring all specified tags to match, for example, `{"$and": ["production", "validated"]}`.
  * An OR condition requiring at least one specified tag to match, for example, `{"$or": ["production", "development"]}`.
  * Complex nested conditions: `{"$or": ["production", {"$and": ["validated", "reviewed"]}]}`.
* `properties` **mapping** (optional) Specifies the properties that matching projects must have. Can be provided in the following ways:
  * A mapping of key-value pairs where each key is a property name and each value can be:
    * A string: The property must have exactly this value, for example, `{"department": "genomics"}`.
    * A boolean `true`: The property must exist with any value, for example, `{"confidential": true}`.
  * An AND condition requiring all specified property constraints to match, for example, `{"$and": [{"department": "genomics"}, {"confidential": true}]}`.
  * An OR condition requiring at least one specified property constraint to match, for example, `{"$or": [{"department": "genomics"}, {"department": "proteomics"}]}`.
  * Complex nested conditions: `{"$or": [{"department": "genomics"}, {"$and": [{"confidential": true}, {"status": "active"}]}]}`.
* `cloudAccount` **string** (optional) If specified, limits results to projects associated with the provided cloud account ID.
* `provider` **string** (optional) If specified, the resulting set contains only projects that are associated with the provider ID.
* `region` **string or array of strings** (optional) For a string value, limits results to projects matching the specified `region`. For an array, limits results to projects with `region` matching any of the specified strings.
* `public` **boolean** (optional) If true, includes only public projects in the result set. If false, excludes all public projects.
* `created` **mapping** (optional) If at least one of the following keys exists, limits results to projects created in the specified time period. Without these keys, no creation time constraints apply. An error occurs if a `created` hash lacks at least one key.
  * `after` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or after this time.
  * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or before this time.
* `describe` **boolean or mapping** (optional) Controls whether extra metadata is retrieved with results. Defaults to `false`.
  * If a **mapping**, provides input for [`/project-xxxx/describe`](https://documentation.dnanexus.com/developer/data-containers/projects#api-method-project-xxxx-describe) calls on each returned project.
  * Allows the following keys:
    * `monthlyComputeLimit`
    * `currentMonthComputeUsage`
    * `currentMonthComputeAvailableBudget`
    * `monthlyEgressBytesLimit`
    * `currentMonthEgressBytesUsage`
    * `currentMonthEgressBytesAvailableBudget`
    * `monthlyStorageLimit`
    * `currentMonthExpectedStorageUsage`
    * `currentMonthStorageAvailableBudget`
* `starting` **string** (optional) Continue a previous query that had reached its limit. The value that was returned as `next` in the previous query's output should be provided here.
* `limit` **integer** (optional) Maximum number of projects that are returned. Defaults to `1000`.
  * Must be no more than `1000`.
* `containsPHI` **boolean** (optional) If set to true, only projects that contain PHI data are retrieved. If set to false, only projects that do not contain PHI data are retrieved.

#### Outputs

* `results` **array of mappings** List of results, each with the following fields:
  * `id` **string** ID of the resulting project.
  * `public` **boolean** Whether the project is public.
  * `level` **string** The explicit project permission the requesting user has to the corresponding project. May be "NONE".
  * `tre` **mapping** TRE association details for the project. Only present when the project is associated with a [Trusted Research Environment](https://documentation.dnanexus.com/developer/api/trusted-research-environments).
    * `treId` **string** ID of the TRE.
    * `treApplicationId` **string** ID of the Data Access Request used to create the project.
    * `workspaceType` **string** The TRE workspace classification of the project. Defaults to `"restricted"`.
  * `describe` **mapping** The output of the corresponding project's describe method if the input `describe` was true or a mapping. This mapping may contain the key `level` with a corresponding value of "NONE", unlike the output of `/system/findProjects`.
* `next` **string** (nullable) Pagination cursor, or `null` if all results are included in `results`. If a string, supply this value to `starting` in a subsequent query to retrieve more results.

#### Errors

* PermissionDenied
  * The requesting user is not an ADMIN of the organization
  * The requesting user does not have a full scope token

### API Method: `/org-xxxx/findApps`

#### Specification

Lists all apps that are billed to the org. The ordering of results is arbitrary. Only ADMINs of the org are allowed to perform this operation.

This operation behaves similarly to [`/system/findApps`](https://documentation.dnanexus.com/developer/search#api-method-system-findapps), except that, by default, it returns **all** apps billed to the org, regardless of whether the app has been published, or whether the requesting user is either a developer or on the authorized users list.

Org ADMINS can call `/app-xxxx/addDeveloper` on any app returned by this API method.

#### Inputs

* `name` **string or mapping** (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields:
  * `regexp` **string** (mutually exclusive with `glob`, required if `glob` is not present) A [PCRE](https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions) regular expression that the name of all results must match.
  * `flags` **string** (optional, can only be present if `regexp` is present) This field can only have value `"i"` to enable case-insensitive matching for the regular expression.
  * `glob` **string** (mutually exclusive with `regexp`, required if `regexp` is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are `"*"` (0 or more characters) and `"?"` (1 character).
* `category` **string or mapping** (optional) Specifies the category or categories that matching apps must have. Can be provided in the following ways:
  * A string to match a single category exactly, for example, `"Alignment"`.
  * An AND condition requiring all specified categories to match, for example, `{"$and": ["Alignment", "NGS"]}`.
  * An OR condition requiring at least one specified category to match, for example, `{"$or": ["Alignment", "Variant Calling"]}`.
  * Complex nested conditions: `{"$or": ["Alignment", {"$and": ["NGS", "RNA-Seq"]}]}`.
* `allVersions` **boolean** (optional) Set to true to include all app versions, not only those tagged with "default". Defaults to `false`.
* `published` **boolean** (optional) Set to true for published apps only, false for unpublished apps only. If omitted, returns both published and unpublished apps.
* `createdBy` **string** (optional) ID of the user who created the app.
* `developer` **string** (optional) ID of a developer the app must have.
* `authorizedUser` **string** (optional) One of a userID, an orgID, or the string "PUBLIC", that must exist in each app's `authorizedUsers` list.
* `modified` **mapping** (optional) If at least one of the following keys is specified, the resulting apps must have been last modified in the indicated time period. If not specified, there is no constraint on when the app was last modified. If a `modified` hash does not contain at least one of the following keys, an error is thrown.
  * `after` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) Limits results to those modified at or after this time.
  * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) Limits results to those modified at or before this time.
* `created` **mapping** (optional) If at least one of the following keys is specified, the resulting apps must have been created in the indicated time period. If not specified, there is no constraint on app creation time. If a `created` hash does not contain at least one of the following keys, an error is thrown.
  * `after` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or after this time.
  * `before` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) (optional) If specified, only return results created at or before this time.
* `describe` **boolean or mapping** (optional) Controls whether extra metadata is retrieved with the results. Defaults to `false`.
  * If a **mapping**, represents the input for calling [`/app-xxxx/describe`](https://documentation.dnanexus.com/developer/running-analyses/apps#api-method-app-xxxx-yyyy-describe) on each of the returned results.
* `starting` **mapping** (optional) Continue a previous query that had reached its limit. The value that was returned as `next` in the query's output should be provided here.
* `limit` **integer** (optional) Maximum number of results to return. Defaults to `1000`. Must be between 1 and 1000.

#### Outputs

* `results` **array of mappings** List of results, each with the following fields:
  * `id` **string** ID of the app.
  * `describe` **mapping** The output of the result's corresponding describe method if `describe` was set to true or a mapping.
* `next` **mapping** (nullable) Pagination cursor, or `null` if all results were reported in `results`. If a mapping, pass this value directly to `starting` in a subsequent query if you need more results.

#### Errors

* PermissionDenied
  * The requesting user is not an ADMIN of the organization
  * The requesting user does not have a full scope token

### API Method: `/org-xxxx/removeMember`

#### Specification

Removes the specified user from the org. The requesting user may remove any org member, including themselves, from the org. By default, this operation also revokes all permissions that the specified user has to projects and/or apps that are billed to the org. On completion, the specified user may no longer perform any action that can incur charges to the org.

The requesting user must be an ADMIN of the org, but does **not** need ADMINISTER permission to projects or developer access to apps whose permissions may be modified by this operation.

When removing another member from the org, the requesting user may receive elevated permissions to projects and/or apps to prevent orphaned resources. For example, the requesting user receives ADMINISTER permission to a project only if the specified user is the sole user with ADMINISTER permission. Similarly, the requesting user receives developer access to an app only if the specified user is the sole developer. The requesting user receives no elevated permissions when removing themselves from the org.

If the specified user is **not** a member of the org at invocation time, their permissions to projects and/or apps billed to the org remain unchanged.

#### Inputs

* `user` **string** (required) ID of the user to remove from the org.
* `revokeProjectPermissions` **boolean** (optional) whether to revoke all explicit permissions granted to `user` to projects billed to the org. The requesting ADMIN does **not** need to have ADMINISTER permission to projects billed to the org that are modified because of this operation. Defaults to `true`.
* `revokeAppPermissions` **boolean** (optional) whether to revoke all explicit developer and authorized accesses granted to `user` to apps billed to the org. The requesting ADMIN does **not** need to have developer access to apps billed to the org that are modified because of this operation. Defaults to `true`.

#### Outputs

* `id` **string** ID of the manipulated org.
* `projects` **mapping** Mapping with the following key-value pairs:
  * **key** — ID of the project to which the specified user was revoked explicit permission.
  * **value** **boolean** — whether the requesting administrator was granted ADMINISTER permission to the corresponding project.
* `apps` **mapping** Mapping with the following key-value pairs:
  * **key** — name of the app to which the specified user was revoked all explicit accesses.
  * **value** **boolean** — whether the requesting administrator was granted developer access to the corresponding app.

#### Errors

* InvalidState
  * The requesting user may not remove themselves if they are the only ADMIN in the org
* PermissionDenied
  * Must have full scope auth token
  * Must be an ADMIN of the org

### API Method: `/org-xxxx/findMembers`

#### Specification

Finds all members of the org, subject to the constraints specified by the requesting user.

The requesting user may be required to have a certain minimum org membership level to perform this operation. To bypass the minimum org membership level restriction and view the membership information of oneself, invoke [`/org-xxxx/describe`](#api-method-org-xxxx-describe).

The ordering of the returned members is ascending by ID.

#### Inputs

* `level` **string** (optional) Restrict results to members with the specified membership level.
  * Must be one of `"MEMBER"` or `"ADMIN"`.
* `id` **array of strings** (optional) If specified, the resulting list of members must have user IDs among this list of IDs. The array may contain no more than 1000 elements.
* `describe` **boolean or mapping** (optional) Controls whether extra metadata is retrieved with results. Defaults to `false`.
  * If a **mapping**, represents the input for describing each member in the result set. See [`/user-xxxx/describe`](https://documentation.dnanexus.com/developer/users#api-method-user-xxxx-describe) for more information.
* `starting` **mapping** (optional) Continue a previous query that had reached its limit. The non-null value that was returned as `next` in that query's output should be provided here.
* `limit` **integer** (optional) Maximum number of members that may be returned. Defaults to `1000`.
  * Must be no more than `1000`.

#### Outputs

* `results` **array of mappings** List of results, each with the following fields:
  * `id` **string** ID of the org member.
  * `level` **string** Membership level of the member in this org.
  * `allowBillableActivities` **boolean** Whether the corresponding member can perform billable activities on behalf of the org (see [org permission flags](#org-permission-flags) for more information).
  * `projectAccess` **string** The maximum project permission the corresponding member is granted via the org to projects explicitly shared with this org.
  * `appAccess` **boolean** Whether the corresponding member can access and run apps shared with this org.
  * `treManagement` **boolean** Whether the corresponding member can create and manage TREs for this org.
  * `describe` **mapping** Metadata about the org member if `describe` was true or a mapping. The output is equivalent to that of [`/user-xxxx/describe`](https://documentation.dnanexus.com/developer/users#api-method-user-xxxx-describe), with the exception that the extra keys are not present if the requesting user is also the member being described. The mapping contains a subset of the following keys:
    * `id`
    * `class`
    * `first`
    * `last`
    * `middle`
    * `handle`
* `next` **mapping** (nullable) Pagination cursor, or `null` if all results were reported in `results`. If a mapping, pass this value directly to `starting` in a subsequent query if you need more results.

#### Errors

* PermissionDenied
  * The requesting user does not have a sufficient org membership level. See [memberListVisibility](#org-policies) for more information. `/org-xxxx/describe` may be invoked to view the requesting user's own org membership information.
  * Must have full scope auth token

### API Method: `/org-xxxx/destroy`

#### Specification

Destroys the specified org. All members are removed from the organization. Any project or app permissions granted to the org are revoked.

#### Inputs

* None

#### Outputs

* `id` **string** ID of the organization.

#### Errors

* InvalidState
  * Existing projects and/or apps are billed to this org
* PermissionDenied
  * The requesting user must be an ADMIN of the org
  * Must have full scope auth token

### API Method: `/org-xxxx/bulkUpdateProjectLimit`

#### Inputs

* `projects` **array of strings** (required) One or more project IDs to update. The array may contain no more than 1000 elements.
* `monthlyComputeLimit` **integer** (optional, nullable) The project-level compute spending limit.
* `monthlyStorageLimit` **number** (optional, nullable) The project-level storage spending limit.
* `monthlyEgressBytesLimit` **integer** (optional, nullable) The project-level egress spending limit.
* `dryRun` **boolean** (optional) If set to true, the final update call is not performed. Defaults to `false`.

#### Outputs

* `updatedCount` **integer** The number of projects that were updated (or the number of projects that could have been updated if `dryRun` is true).

#### Errors

* InvalidInput
  * If neither `monthlyComputeLimit` nor `monthlyEgressBytesLimit` nor `monthlyStorageLimit` is provided.
  * If `monthlyComputeLimit` is not an integer or `null` or is not larger than or equal to zero.
  * If `monthlyEgressBytesLimit` is not an integer or `null` or is not larger than or equal to zero.
  * If `monthlyStorageLimit` is not a number or `null` or is not larger than or equal to zero.
  * `dryRun` is not a boolean.
  * If any project does not belong to the org.
  * If there are more than 1000 project IDs.
* ResourceNotFound
  * If a `projectId` is not found.
* PermissionDenied
  * If `licenseFeature.monthlyProjectSpendingLimit` is not enabled.
  * If the requesting user is not an org ADMIN.
  * The requesting user does not have a full-scope token.

{% hint style="info" %}
Licenses are required 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 %}


---

# 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/organizations.md?ask=<question>
```

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.