Ctrlk
APIDownloadsIndex of dx CommandsLegal
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ChatGPT

Organizations

Learn about creating and managing organizations (orgs) via the DNAnexus Platform API.

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 with 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. 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 by default.

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 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) for the org. In the UI, this permission appears as Research Environment Management.

The following flags are custom role permissions that delegate specific administrative capabilities to org MEMBERs. Org ADMINs always have these permissions implicitly set to true. Only org ADMINs can grant these permissions to MEMBERs.

  • archivalManagement boolean Whether the user can execute archive and unarchive operations org-wide, including use of the allCopies flag on /project-xxxx/archive, /project-xxxx/unarchive, and the archivalInfoForOrg option on /class-xxxx/listProjects, regardless of project membership. Defaults to false for MEMBERs.

  • projectMemberDemotion boolean Whether the user can call /project-xxxx/decreasePermissions on any org project without being a project member or project admin, and can use the member filter on /org-xxxx/findProjects to audit another member's project access. Defaults to false for MEMBERs.

  • dataDeletion boolean Whether the user can call /class-xxxx/removeObjects with overrideProjectAccess: true to delete objects from projects and containers billed to the org, regardless of project or container membership. Defaults to false for MEMBERs.

  • dataSearch boolean Whether the user can call /class-xxxx/listProjects with allCopiesForOrg: <org-id> to discover all copies of an object across the entire organization, regardless of project membership. Defaults to false for MEMBERs.

Org ADMINs have all available org permissions. Custom role permissions (archivalManagement, projectMemberDemotion, dataDeletion, dataSearch) are always true for org ADMINs.

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

Any org ADMIN can configure permission flags for org MEMBERs using /org-xxxx/setMemberAccess.

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) 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). 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. Must be one of "ADMIN" or "MEMBER". 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. 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, and related resources) 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 (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 pre-signed URLs) 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.

A license is required to set the following Monthly Project Spending Limit for Computing and Egress policies. Contact DNAnexus Sales for more information.

  • 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 to enforce termination behaviors when the project compute spending limit is exceeded. Defaults to false in /org/new.

  • enforceTerminationForProjectEgressBytesLimit boolean (optional) Whether to enforce termination behaviors when the project egress spending limit is exceeded. Defaults to false in /org/new.

  • enforceTerminationForProjectStorageLimit boolean (optional) Whether to 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, but does not allow billable activities (such as creation of projects or uploading of data). Contact DNAnexus Sales to create a billable org.

Inputs

  • handle string (required) A case-insensitive unique handle for the org. The chosen handle must not be 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 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.

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

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 for more information.

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 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.

  • 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.

    • 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 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 for more information).

  • appAccess boolean Whether the requesting user can access and run apps shared with the org (see Organization 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 for more information).

  • archivalManagement boolean Whether the requesting user can perform org-wide archive and unarchive operations (see Organization permission flags for more information).

  • projectMemberDemotion boolean Whether the requesting user can decrease project member permissions on any org project without being a project member (see Organization permission flags for more information).

  • dataDeletion boolean Whether the requesting user can remove objects from any org project or container regardless of membership (see Organization permission flags for more information).

  • dataSearch boolean Whether the requesting user can list all copies of objects across the entire organization (see Organization 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.

  • permittedRegions array of strings The regions in which this org can create projects. For more information about regions, see Regions.

  • memberLimit integer (nullable) The maximum number of members that may belong to this org. A value of null indicates that no member limit is set. This field can only be set by DNAnexus Platform admins.

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 Last date for which computeCharges were calculated.

  • computeChargesComputedAt timestamp Time when computeCharges were updated in the system.

  • storageCharges number Running total of storage charges (in dollars) for the account.

  • storageChargesReflectedUntil timestamp Last date for which storageCharges were calculated.

  • storageChargesComputedAt timestamp Time that storageCharges were last updated in the system.

  • dataEgressCharges number Running total of data egress charges (in dollars) for the account.

  • dataEgressChargesReflectedUntil timestamp Last date for which dataEgressCharges were calculated.

  • dataEgressChargesComputedAt timestamp Time that dataEgressCharges were last updated in the system.

  • dearchivalCharges number Running total of data dearchival charges (in dollars) for the account.

  • dearchivalChargesReflectedUntil timestamp Last date for which dearchivalCharges were calculated.

  • dearchivalChargesComputedAt timestamp Time that dearchivalCharges were last updated in the system.

  • dbclusterCharges number Running total of DB cluster charges (in dollars) for the account.

  • dbclusterChargesReflectedUntil timestamp Last date for which dbclusterCharges were calculated.

  • dbclusterChargesComputedAt timestamp 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.

        • 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). 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).

        • 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 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 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. 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 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.

A license is required to enable org admins to provision accounts for other users. Contact DNAnexus Sales for more information.

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.

  • monthlyReportsProjectId string The ID of the project that stores monthly project usage reports.

  • 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.

A license is required to use the Forwarding Job Logs to a customer's Splunk feature. Contact DNAnexus Sales for more information.

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 for details)

  • monthlyProjectEgressBytesLimitDefault (see Org Policies for details)

  • monthlyProjectStorageLimitDefault (see Org Policies for details)

  • enforceTerminationForProjectComputeLimit (see Org Policies for details)

  • enforceTerminationForProjectEgressBytesLimit (see Org Policies for details)

  • enforceTerminationForProjectStorageLimit (see Org Policies for details)

  • projectSpendingLimitNotificationThreshold (see Org Policies for details)

A license is required to use the Monthly Project Spending Limit for Storage feature. Contact DNAnexus Sales for more information.

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 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.

  • 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 a customer's 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>"}

A license is required to use the Forwarding Job Logs to a Customer's Splunk feature. Contact DNAnexus Sales for more information.

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 or equal to zero.

    • If monthlyProjectEgressBytesLimitDefault in policies is not an integer and not null, or not larger than or equal to zero.

    • If monthlyProjectStorageLimitDefault in policies is not a number and not null, or not larger than or equal to 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 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 but 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

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 for more information.

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 when level is "MEMBER". 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 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".

The following custom role permission flags (see Org Permission Flags for more information) may also be included. Only org ADMINs can set these flags.

  • archivalManagement boolean (optional) Whether the invitee can perform org-wide archive and unarchive operations. Defaults to false.

  • projectMemberDemotion boolean (optional) Whether the invitee can decrease project member permissions on any org project without being a project member. Defaults to false.

  • dataDeletion boolean (optional) Whether the invitee can remove objects from any org project or container regardless of membership. Defaults to false.

  • dataSearch boolean (optional) Whether the invitee can list all copies of objects across the entire organization. Defaults to false.

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 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

    • The requesting user is not an ADMIN of the organization but attempted to set any of archivalManagement, projectMemberDemotion, dataDeletion, or dataSearch to true for the invitee

API Method: /org-xxxx/setMemberAccess

Specification

Modifies the organization membership statuses or permission flags for members of the organization. To add new users to the organization, refer to /org-xxxx/invite.

When upgrading a user's membership status from "MEMBER" to "ADMIN", all custom role permission flags (archivalManagement, projectMemberDemotion, dataDeletion, dataSearch) are implicitly set to true. When downgrading a user's membership status from "ADMIN" to "MEMBER", all custom role permission flags default to false. If any permission flag is explicitly provided during a downgrade, the provided value takes precedence.

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 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 manage Trusted Research Environments (TREs) for the org when level is "MEMBER".

      • level string The membership status to set for the user. Must be one of "MEMBER" or "ADMIN".

        • Permission flags are prohibited if level is "ADMIN" and optional otherwise.

      • 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".

      • archivalManagement boolean (optional) Whether the corresponding user can perform org-wide archive and unarchive operations. Only org ADMINs can set this flag to true.

      • projectMemberDemotion boolean (optional) Whether the corresponding user can decrease project member permissions on any org project without being a project member. Only org ADMINs can set this flag to true.

      • dataDeletion boolean (optional) Whether the corresponding user can remove objects from any org project or container regardless of membership. Only org ADMINs can set this flag to true.

      • dataSearch boolean (optional) Whether the corresponding user can list all copies of objects across the entire organization. Only org ADMINs can set this flag to true.

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

    • The requesting user is not an ADMIN of the organization but attempted to set any of archivalManagement, projectMemberDemotion, dataDeletion, or dataSearch 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 permitted to perform this operation in general. MEMBERs may use the member filter to query their own user ID, or to query another member's project access if they have the projectMemberDemotion permission.

Projects are ordered by:

  • Last modified time stamp (descending), then

  • ID (ascending)

This behaves similarly to /system/findProjects.

Inputs

  • member string (optional) If specified, limits results to projects that the given user ID has access to within the organization. Requires the requesting user to be an org ADMIN, or to be a MEMBER who is querying their own user ID or has projectMemberDemotion: true.

  • 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 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 (optional) If specified, only return results created at or after this time.

    • before timestamp (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 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. Provide the value that was returned as next in the previous query's output.

  • 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.

      • 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 and no member filter is provided

    • The requesting user does not have a full scope token

    • The requesting user is a MEMBER without projectMemberDemotion and attempted to use the member filter

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, 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 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 (optional) Limits results to those modified at or after this time.

    • before timestamp (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 (optional) If specified, only return results created at or after this time.

    • before timestamp (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 on each of the returned results.

  • starting mapping (optional) Continue a previous query that had reached its limit. Provide the value that was returned as next in the query's output.

  • 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 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 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 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 for 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 for 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 from which the specified user's explicit permission was revoked.

    • 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 from which the specified user's explicit accesses were revoked.

    • 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.

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 for more information.

  • starting mapping (optional) Continue a previous query that had reached its limit. Provide the non-null value that was returned as next in that query's output.

  • 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 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 manage Trusted Research Environments (TREs) for this org.

    • archivalManagement boolean Whether the corresponding member can perform org-wide archive and unarchive operations.

    • projectMemberDemotion boolean Whether the corresponding member can decrease project member permissions on any org project without being a project member.

    • dataDeletion boolean Whether the corresponding member can remove objects from any org project or container regardless of membership.

    • dataSearch boolean Whether the corresponding member can list all copies of objects across the entire organization.

    • describe mapping Metadata about the org member if describe was true or a mapping. The output is equivalent to that of /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 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 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

Specification

Updates project-level spending limits for one or more projects billed to the org.

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 eligible for update 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.

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 for more information.

Last updated

Was this helpful?