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

Trusted Research Environments API

Learn about creating and managing Trusted Research Environments (TREs) via the DNAnexus Platform API.

A Trusted Research Environment (TRE) is a DNAnexus entity that provides a secure, controlled environment for accessing and analyzing sensitive datasets. TREs enforce data governance policies, manage data inventories, and control user access through configurable workspace restrictions.

Creating a TRE requires the requesting user to be an org ADMIN of the billing organization, have the treManagement permission enabled for that org, and use an org with the TRE license. Users with the treManagement permission can also be selected as TRE-specific admins. Each TRE is associated with a billing organization and a region, and provides data inventories, workspace policies, and role-based access controls for researchers.

Apollo and Trusted Research Environments licenses are required to use Trusted Research Environments on the DNAnexus Platform. Contact DNAnexus Sales for more information.

TRE States

A TRE progresses through the following lifecycle states:

  • "draft" The initial state after creation. All TRE settings, including inventory, policies, and user management, are fully configurable.

  • "active" The TRE is operational and available for downstream use, such as data requests and project creation. Inventory cannot be changed. Policies and user management remain configurable.

  • "amending" A transitional state entered by deactivating an active TRE (appears as Maintenance in the UI). Inventory can be updated with a new pending version. Policies and user management remain configurable.

Setting
Configurable in draft
Configurable in amending
Configurable in active

name, description

Yes

Yes

Yes

region, billTo

Yes

No

No

customizedRateCard, customizedURL

Yes

No

No

Inventory

Yes

Yes

No

Policies

Yes

Yes

Yes

allowedProjects

Yes

Yes

Yes

features.enforceFullCohortSelection

Yes

No

No

User management

Yes

Yes

Yes

Add or remove review steps

Yes

No

No

Add or remove reviewers

Yes

Yes

Yes

TRE Roles

The following roles govern access and administration of a TRE:

  • TRE Admin Full administrative control over a specific TRE, including configuration, activation, and user management. TRE admins receive ADMIN access to inventory projects when the TRE is active or amending. Any user with the treManagement permission (displayed as Research Environment Management in the Org settings UI) can be added as a TRE admin.

  • Reviewer Access to review Data Access Requests. Reviewers are assigned to specific review steps and can approve or reject access requests for their assigned steps. Reviewers receive VIEW access to showcase projects and can discover the TRE in the same way as authorized users.

  • Authorized User Visibility access to discover the TRE and view its basic details and policies. Authorized users can be individual users, orgs, or the PUBLIC placeholder (making the TRE discoverable by all platform users). Authorized users can create Data Access Requests.

TRE Robot User

When a TRE is activated, the platform provisions and manages a TRE robot user and a TRE working project for that TRE. These resources support internal TRE operations, including dispensal processing and temporary processing artifacts.

The TRE robot user and the TRE working project are tied to the TRE billing context. Operational compute and storage for these internal workflows are billed to the same billTo organization as the TRE.

Manage these resources only through supported TRE controls. Do not manually remove or modify TRE robot user access or TRE working project permissions. Manual changes can break dispensal and support workflows.

Use supportOrg and allowSupportAccess to control troubleshooting access to the TRE working project. Keep support access disabled unless active debugging is required.

Data Access Request Review Steps

TRE admins configure data access request review steps that define the approval workflow for Data Access Requests. Each review step has a unique identifier, a name, and a description, and is assigned one or more reviewers.

When an access request is submitted, each review step must be independently resolved (approved or rejected) by a reviewer assigned to that step. The overall access request decision follows this priority:

Priority
Condition
Overall decision

1

Any review step is rejected

Rejected

2

No rejected steps, but any step is pending

Pending

3

All steps are approved

Approved

Review steps can only be added or removed when the TRE is in draft state. Reviewers can be added or removed in any state. A TRE must have at least one review step with at least one reviewer per step before it can be activated.

TRE Inventory

Each TRE manages one or more data inventories that define the datasets available to researchers.

A TRE inventory includes:

  • File inventory - Required, A file, such as a TSV, associated with a project. This inventory type is required.

  • Data type groups - Required, A file that defines the data collections and fields available for request selection. This inventory type is required.

  • Tabular data inventory - Optional, An Apollo dataset in a project associated with the hosting billTo org.

  • Showcase data inventory - Optional, typically a subset of the full Tabular data dataset used for exploring and selecting cohorts in the data set. The project hosting the showcase dataset must be separate from the projects containing the file and tabular data inventories.

  • Assays - Optional, An array of assay configurations, each linking entities, projects, datasets, and assay PID map databases. Assays are valid only when the Tabular data inventory is enabled.

The enableDataset and enableShowcase flags control whether the optional tabular data and showcase inventories are enabled. If enableShowcase is false, the TRE must have features.enforceFullCohortSelection set to true before activation.

Each inventory has a version that follows semantic versioning.

Inventories also have their own states:

  • "active" The inventory configuration for the current data release.

  • "inactive" A historical inventory configuration, replaced by a later version.

  • "pending" A new inventory configuration that is not yet effective. Pending inventories become active on TRE activation.

Inventory settings can only be changed when the TRE is in the draft or amending state.

TRE Policies

Policies define workspace-level restrictions that the TRE enforces on projects.

Each policy key maps to an existing project data access control. Policy values follow these rules:

  • true or false The setting is enforced at the TRE level and cannot be overridden by project admins.

  • null The TRE does not enforce this setting. Project admins can configure it independently.

The available policy keys are:

  • restricted boolean (nullable) Controls whether users can copy data out of the project. In the UI, this policy is labeled Copy Access.

  • protected boolean (nullable) Defines which roles can delete data from the project. In the UI, this policy is labeled Delete Access.

  • downloadRestricted boolean (nullable) Controls whether users can download data from the project. In the UI, this policy is labeled Download Access.

  • externalUploadRestricted boolean (nullable) Controls whether users can upload files and create data from outside the DNAnexus Platform. In the UI, this policy is labeled External Upload Access. Requires the externalUploadRestrictedControl feature switch.

  • previewViewerRestricted boolean (nullable) Controls whether users can preview and download file content up to 100 KB. In the UI, this policy is labeled File Preview.

  • databaseUIViewOnly boolean (nullable) Controls whether databases are restricted to platform UI access only. When true, programmatic access via apps, HTTPS environments, and API requests is not allowed. In the UI, this policy is labeled Programmatic Database Access.

  • containsPHI boolean (nullable) Enables enhanced security controls for projects containing PHI, in compliance with HIPAA. Once enabled, this setting cannot be disabled. In the UI, this policy is labeled PHI Data Protection. Requires the phiFeaturesEnabled feature switch.

  • httpsAppIsolatedBrowsing boolean (nullable) Enforces isolated browsing for all HTTPS apps, preventing data copy and download during app sessions. In the UI, this policy is labeled Isolated Browsing Enforcement.

  • jobOutboundInternet boolean (nullable) Controls whether jobs in the project can access the public internet. In the UI, this policy is labeled Job Outbound Internet Access.

  • displayDataProtectionNotice boolean (nullable) Displays a configurable data protection notice that users must acknowledge before accessing the project. In the UI, this policy is labeled Data Protection Notice. Requires the dataProtectionNotice feature switch.

Changes to policies take effect immediately on TRE projects. When a policy value changes via /tre-xxxx/setPolicies, the corresponding project-level flag is synchronized on existing TRE projects.

Non-Configurable Restrictions

Beyond the configurable policies above, the platform enforces a set of non-configurable restrictions on all TRE projects. These restrictions cannot be overridden by project admins or TRE admins.

General Restrictions

The following operations are forbidden in all TRE projects:

  • Creating new apps via /app/new is not allowed.

  • Creating new global workflows via /globalworkflow/new is not allowed.

  • Transferring TRE projects via /project-xxxx/transfer is not allowed.

  • Accepting a transfer for a TRE project via /project-xxxx/acceptTransfer is not allowed.

  • Changing the billTo of a TRE project via /project-xxxx/update is not allowed.

  • Updating workflows in TRE projects via /workflow-xxxx/update must continue to comply with TRE execution restrictions.

  • Inviting a user to a TRE project via /project-xxxx/invite requires the invitee to be a request owner or collaborator on the Data Access Request associated with the project.

  • Removing dispensed data objects via /class-xxxx/removeObjects is not allowed. Objects placed into a TRE project by the platform's dispensal process are protected from deletion. Dispensed data is removed only when the entire project is destroyed. For more information, see Dispensal.

Clone Restrictions

Cloning objects between TRE projects via /class-xxxx/clone or /database-xxxx/relocate is subject to the following rules:

  • The source and destination projects must be associated with the same Data Access Request.

  • Cloning between TRE projects and non-TRE projects is not allowed. Projects in the allowedProjects list for this TRE are exempt from this restriction.

Execution Restrictions

The following restrictions apply to job execution in TRE projects. These affect /applet-xxxx/run, /app-xxxx[/yyyy]/run, /workflow-xxxx/run, and /globalworkflow-xxxx[/yyyy]/run:

  • allowSSH is not allowed.

  • httpsApp can expose HTTPS only for allowlisted HTTPS apps, and only on port 443.

  • singleContext is enforced as true.

  • allProjects with UPLOAD access or higher access level is not allowed.

  • projectCreation is not allowed.

API Method Specifications

API method: /tre-xxxx/delete

Specification

Deletes a TRE and its associated inventory. The TRE can only be deleted when:

  • The TRE isn't associated with any data access requests or projects.

  • The TRE is in the draft or amending state.

  • The requesting user must be a TRE admin.

On deletion, authorized users are removed from the hosting project of the showcase dataset.

Inputs

None.

Outputs

  • id string ID of the deleted TRE.

Errors

  • InvalidState

    • The TRE has active access requests or projects associated with it.

  • ResourceNotFound

    • The TRE was not found.

  • PermissionDenied

    • The requesting user must be a TRE admin.

    • The requesting user must use a full-scope token.

API method: /tre/new

Specification

Creates a new TRE and places it in the draft state. The requesting user must be an org ADMIN of the billing organization, must have the treManagement permission flag enabled for that org, and the org must have the TRE license. On creation, the requesting user is automatically selected as a TRE admin.

Inputs

  • handle string (required) A unique identifier for the TRE. The handle must be lowercase, between 3 and 63 characters long, and follow the same constraints as org handles.

  • name string (required) A descriptive name for the TRE, between 1 and 256 characters long.

  • description string (required) Detailed information about the TRE, between 1 and 5,000 characters long.

  • summary string (required) A short summary of the TRE, between 1 and 500 characters long.

  • billTo string (required) The org ID of the data hosting organization.

  • region string (required) One of the allowed DNAnexus regions for the billing org, for example, aws:us-east-1.

  • customizedRateCard boolean (optional) If true, the TRE uses the rates of the hosting org rather than standard rates. Defaults to false.

  • customizedURL boolean (optional) If true, the TRE uses a customized URL. Defaults to false.

Outputs

  • id string ID of the newly created TRE (for example, tre-genomics).

Errors

  • InvalidInput

    • handle must be lowercase and between 3 and 63 characters long.

    • name must not be empty and must not exceed 256 characters.

    • description must not exceed 5,000 characters.

    • region is not one of the allowed regions for the billing org.

  • ResourceNotFound

    • The org specified in billTo was not found.

  • PermissionDenied

    • The requesting user must be an org ADMIN of the org specified in billTo.

    • The requesting user must have the treManagement permission flag enabled for the org specified in billTo.

    • The org specified in billTo must have the TRE license.

    • The requesting user must use a full-scope token.

API method: /tre-xxxx/update

Specification

Updates basic information for a TRE. The set of modifiable fields depends on the current state of the TRE. In draft state, all the following fields can be modified. In active or amending state, only name, description, and allowSupportAccess can be modified. The requesting user must be a TRE admin.

Inputs

  • name string (optional) A descriptive name for the TRE, between 1 and 256 characters long.

  • description string (optional) Detailed information about the TRE, between 1 and 5,000 characters long.

  • billTo string (optional) The org ID of the data hosting organization. Only modifiable in draft state.

  • region string (optional) One of the allowed DNAnexus regions. Only modifiable in draft state.

  • supportOrg string (optional) Org ID used for support users when troubleshooting access is enabled. Only modifiable in draft state.

  • allowSupportAccess boolean (optional) Whether users from supportOrg can access the TRE working project for troubleshooting.

  • customizedRateCard boolean (optional) Whether the TRE uses the rates of the hosting org. Only modifiable in draft state.

  • customizedURL boolean (optional) Whether the TRE uses a customized URL. Only modifiable in draft state.

Outputs

  • id string ID of the updated TRE.

Errors

  • InvalidInput

    • name must not exceed 256 characters.

    • description must not exceed 5,000 characters.

  • InvalidState

    • Fields other than name, description, and allowSupportAccess cannot be modified when the TRE is in active or amending state.

  • ResourceNotFound

    • The TRE was not found.

  • PermissionDenied

    • The requesting user must be a TRE admin.

API method: /tre-xxxx/setInventory

Specification

Sets the inventory for a TRE. Each TRE has a 1:N relationship with inventory objects. In draft state, the inventory is created or updated in place. In amending state, a new pending inventory is created (or updated if one already exists). Pending inventories become active on TRE activation.

Inputs

The file, enableDataset, enableShowcase, dataTypeGroups, and version keys are required. The dataset and showcase mappings are required only when their corresponding enable flags are true. A file-only inventory sets both enableDataset and enableShowcase to false.

  • file mapping (required) File inventory configuration. Must not be an empty mapping {}.

    • project string (required) The project ID containing the file.

    • id string (required) The file ID.

  • enableDataset boolean (required) Whether the inventory includes a Tabular Data Inventory. Defaults to false.

  • dataset mapping (optional) Tabular data inventory configuration. Required when enableDataset is true. Must be omitted when enableDataset is false.

    • project string (required) The project ID containing the dataset.

    • id string (required) The dataset record ID.

  • enableShowcase boolean (required) Whether the inventory includes a Showcase Data Inventory. Defaults to false.

  • showcase mapping (optional) Showcase data inventory configuration. Required when enableShowcase is true. Must be omitted when enableShowcase is false. The project specified here must be different from the projects in file and dataset because authorized users automatically receive access to the project containing the showcase dataset.

    • project string (required) The project ID containing the showcase dataset.

    • id string (required) The showcase record ID.

  • dataTypeGroups mapping (required) Data type group metadata file configuration.

    • project string (required) The project ID containing the data type groups file.

    • id string (required) The file ID for data type group metadata.

  • assays array of mappings (optional) Assay configurations. Valid only when enableDataset is true.

    • entity string (required) The assay entity name.

    • project string (required) The project ID for the assay.

    • workingProject string (required) The working project ID used for assay processing for this inventory entry.

    • dataset string (required) The dataset record ID.

    • assayPidMapDatabase string (required) The unique name of the assay PID map database.

  • version string (required) The inventory version in semantic versioning format (major.minor.patch). Must be greater than the previous active version.

Outputs

  • id string ID of the updated TRE.

Errors

  • InvalidInput

    • file cannot be empty.

    • dataset is required when enableDataset is true.

    • dataset cannot be specified when enableDataset is false.

    • showcase is required when enableShowcase is true.

    • showcase cannot be specified when enableShowcase is false.

    • assays cannot be specified when enableDataset is false.

    • File, dataset, showcase, or assay inventory entries must reference valid projects and objects.

    • dataTypeGroups must reference a valid project and file.

    • The assayPidMapDatabase must reference an existing database.

    • version must follow semantic versioning format and be greater than the previous active version.

    • The requesting user must be an admin of the projects hosting the inventory.

    • All inventory projects must have the same billTo as the TRE.

    • All inventory projects must be in the same region as the TRE.

  • InvalidState

    • Inventory cannot be updated when the TRE is in active state.

  • ResourceNotFound

    • The TRE was not found.

  • PermissionDenied

    • The requesting user must be a TRE admin.

API method: /tre-xxxx/setPolicies

Specification

Sets the workspace policies for the TRE. Policies map to existing project-level restriction flags. When a policy value changes, the corresponding project-level flag is synchronized on existing TRE projects. Project creation for the TRE is temporarily blocked during synchronization to ensure consistency. The requesting user must be a TRE admin.

Inputs

  • restrictedWorkspace mapping (optional) Workspace policies for TRE projects. Each key is a policy name and each value is true, false, or null. See TRE Policies for the list of available policy keys.

Outputs

  • id string ID of the TRE that was modified.

Errors

  • InvalidInput

    • Unrecognized policy key in input.

  • ResourceNotFound

    • The TRE was not found.

  • PermissionDenied

    • The requesting user must be a TRE admin.

API method: /tre-xxxx/addTreAdmins

Specification

Adds users as TRE admins for the specified TRE. If the TRE is in active or amending state, newly added TRE admins are granted ADMIN access to the inventory projects. The requesting user must be a TRE admin.

Inputs

  • users array of strings (required) A list of user IDs to add as TRE admins.

    • The total number of TRE admins must not exceed 100.

Outputs

  • id string ID of the TRE that was modified.

Errors

  • InvalidInput

    • The users array is empty or adding these users exceeds the limit of 100 TRE admins.

  • ResourceNotFound

    • The TRE was not found.

    • One or more users in the list do not exist.

  • PermissionDenied

    • The requesting user must be a TRE admin.

API method: /tre-xxxx/removeTreAdmins

Specification

Removes users from the TRE admin role. If the TRE is in active or amending state, removed users lose their access to the inventory projects. The requesting user must be a TRE admin.

Inputs

  • users array of strings (required) A list of user IDs to remove from the TRE admin role.

Outputs

  • id string ID of the TRE that was modified.

Errors

  • InvalidInput

    • The users array does not contain valid user IDs.

  • ResourceNotFound

    • The TRE was not found.

    • One or more users in the list do not exist.

  • PermissionDenied

    • The requesting user must be a TRE admin.

API method: /tre-xxxx/addAuthorizedUsers

Specification

Adds users or orgs to the authorized users list for the specified TRE. Authorized users can discover and view the TRE. The input list can contain user IDs, org IDs, or the PUBLIC placeholder. If PUBLIC is specified, any user on the platform can discover the TRE, and any existing individual user or org entries are replaced. The requesting user must be a TRE admin.

Inputs

  • users array of strings (required) A list of user IDs, org IDs, or PUBLIC to add as authorized users of the TRE.

Outputs

  • id string ID of the TRE that was modified.

Errors

  • InvalidInput

    • The users array does not contain valid user IDs, org IDs, or PUBLIC.

  • ResourceNotFound

    • The TRE was not found.

    • One or more users or orgs in the list do not exist.

  • PermissionDenied

    • The requesting user must be a TRE admin.

API method: /tre-xxxx/removeAuthorizedUsers

Specification

Removes users or orgs from the authorized users list for the specified TRE. If PUBLIC is in the current list and the input does not include PUBLIC, removing users or orgs has no effect until PUBLIC is also removed. The requesting user must be a TRE admin.

Inputs

  • users array of strings (required) A list of user IDs, org IDs, or PUBLIC to remove from the authorized users list.

Outputs

  • id string ID of the TRE that was modified.

Errors

  • InvalidInput

    • The users array does not contain valid user IDs, org IDs, or PUBLIC.

  • ResourceNotFound

    • The TRE was not found.

    • One or more users or orgs in the list do not exist.

  • PermissionDenied

    • The requesting user must be a TRE admin.

API method: /tre-xxxx/addApplicationReviewStep

Specification

Adds an access request review step to the TRE. Review steps define the stages in the approval workflow for Data Access Requests. Review steps can only be added when the TRE is in draft state. The requesting user must be a TRE admin.

Inputs

  • reviewStepId string (required) A unique identifier for the review step. Must be alphanumeric lowercase without spaces or reserved characters, matching the pattern ^[a-z0-9]{1,256}$.

  • name string (required) A descriptive name for the review step, up to 256 characters.

  • description string (required) A description of the review step, up to 1,000 characters.

Outputs

  • id string ID of the modified TRE.

Errors

  • InvalidInput

    • reviewStepId does not match the required pattern or exceeds 256 characters.

    • name exceeds 256 characters.

    • description exceeds 1,000 characters.

    • A review step with the same reviewStepId already exists.

  • InvalidState

    • The TRE is not in draft state.

  • ResourceNotFound

    • The TRE was not found.

  • PermissionDenied

    • The requesting user must be a TRE admin.

    • The requesting user must use a full-scope token.

API method: /tre-xxxx/updateApplicationReviewStep

Specification

Updates an existing access request review step on the TRE. The requesting user must be a TRE admin.

Inputs

  • reviewStepId string (required) The identifier of the review step to update.

  • name string (optional) The updated name for the review step, up to 256 characters.

  • description string (optional) The updated description for the review step, up to 1,000 characters.

Outputs

  • id string ID of the modified TRE.

Errors

  • InvalidInput

    • reviewStepId does not match an existing review step.

    • name exceeds 256 characters.

    • description exceeds 1,000 characters.

  • ResourceNotFound

    • The TRE was not found.

  • PermissionDenied

    • The requesting user must be a TRE admin.

    • The requesting user must use a full-scope token.

API method: /tre-xxxx/removeApplicationReviewStep

Specification

Removes an access request review step from the TRE. Review steps can only be removed when the TRE is in draft state. If the removed step's reviewers are not assigned to any other review steps, they are also removed from the showcase projects. The requesting user must be a TRE admin.

Inputs

  • reviewStepId string (required) The identifier of the review step to remove.

Outputs

  • id string ID of the modified TRE.

Errors

  • InvalidInput

    • reviewStepId does not match an existing review step.

  • InvalidState

    • The TRE is not in draft state.

  • ResourceNotFound

    • The TRE was not found.

  • PermissionDenied

    • The requesting user must be a TRE admin.

    • The requesting user must use a full-scope token.

API method: /tre-xxxx/addApplicationReviewers

Specification

Adds reviewers to a specific review step of the TRE. Reviewers are granted VIEW access to the showcase projects in the TRE inventories. The requesting user must be a TRE admin.

Inputs

  • reviewStepId string (required) The identifier of the review step.

  • users array of strings (required) A list of user IDs to add as reviewers.

    • The total number of reviewers per step must not exceed 100.

Outputs

  • id string ID of the modified TRE.

Errors

  • InvalidInput

    • reviewStepId is not defined in the TRE.

    • users array contains more than 100 reviewers.

  • ResourceNotFound

    • The TRE was not found.

    • One or more users in the list do not exist.

  • PermissionDenied

    • The requesting user must be a TRE admin.

    • The requesting user must use a full-scope token.

API method: /tre-xxxx/removeApplicationReviewers

Specification

Removes reviewers from a specific review step of the TRE. If a reviewer is removed from all review steps, their VIEW access to the showcase projects is also revoked. The requesting user must be a TRE admin.

Inputs

  • reviewStepId string (required) The identifier of the review step.

  • users array of strings (required) A list of user IDs to remove from the review step.

Outputs

  • id string ID of the modified TRE.

Errors

  • InvalidInput

    • reviewStepId is not defined in the TRE.

  • ResourceNotFound

    • The TRE was not found.

    • One or more users in the list do not exist.

  • PermissionDenied

    • The requesting user must be a TRE admin.

    • The requesting user must use a full-scope token.

API method: /tre-xxxx/getDataTypeGroups

Specification

Returns the contents of the file specified in the dataTypeGroups section of the inventory for the TRE.

Inputs

None.

Outputs

  • results array of mappings The parsed data type groups.

    • name string Name of the data type group.

    • description string Description of the data type group.

    • mandatory boolean Whether the data type group is mandatory.

    • files integer Number of files represented in this data type group.

    • fields array of strings Field IDs represented by this data type group.

    • detailsURL string URL with more details for the data type group.

Errors

  • ResourceNotFound

    • The TRE was not found.

    • The file configured in dataTypeGroups was not found.

  • PermissionDenied

    • The requesting user must be a TRE admin, reviewer, or authorized user of the TRE.

    • The requesting user must use a full-scope token.

  • InvalidState

    • dataTypeGroups is not configured in the TRE inventory.

    • dataTypeGroups.project is not configured in the TRE inventory.

    • dataTypeGroups.id is not configured in the TRE inventory.

    • The configured data type groups file does not contain valid JSON.

    • The configured data type groups file JSON does not conform to the expected output schema.

API method: /tre-xxxx/describe

Specification

Describes a TRE. The output depends on the requesting user's role. Authorized users and reviewers see a subset of basic fields, including active inventory showcase details when a showcase is enabled. TRE admins see all fields.

Inputs

  • fields mapping (optional) Specifies fields to include or exclude from the output.

    • key — requested output field (see "Outputs" section for valid values).

    • value boolean — whether to include the field.

Outputs

The following fields are available to all users who have access to the TRE (authorized users, reviewers, and TRE admins):

  • id string The TRE ID.

  • name string The descriptive name of the TRE.

  • description string Detailed information about the TRE.

  • summary string A short summary of the TRE.

  • handle string The unique handle for the TRE.

  • region string The region of the TRE.

  • billTo string The billing org ID.

  • state string The current state of the TRE.

    • Must be one of "draft", "active", or "amending".

  • public boolean Whether the TRE is publicly discoverable.

  • policies mapping The TRE workspace policies. See TRE Policies.

  • inventory string The active inventory version identifier.

  • showcaseInventory mapping The active inventory details for the showcase section only. Includes the showcase project and record IDs needed to load the showcase dataset in the Cohort Browser.

    • Only present when the active inventory has enableShowcase set to true.

  • allowedProjects array of strings Project IDs exempt from the restriction on cloning between TRE and non-TRE projects. See /tre-xxxx/addAllowedProjects.

  • features mapping TRE feature flags. See /tre-xxxx/setFeatures for available flags.

    • enforceFullCohortSelection boolean Whether all data access requests must include the full participant cohort. When true, the Data Showcase is not accessible to authorized users and cohortMetadataRecords cannot be set on data access requests.

The following fields are available only to TRE admins:

  • inventoryDetails array of mappings Full historical inventory records, each including the inventory configuration, version, state, and activation timestamp. See /tre-xxxx/setInventory for details on inventory configuration.

  • treAdmins array of strings The user IDs of TRE admins.

  • authorizedUsers array of strings The user IDs, org IDs, or PUBLIC entries in the authorized users list.

  • customizedRateCard boolean Whether the TRE uses a customized rate card.

  • customizedURL boolean Whether the TRE uses a customized URL.

  • supportOrg string Org ID for the support org of the TRE that can be used for troubleshooting access.

  • allowSupportAccess boolean Whether troubleshooting access to the TRE working project is enabled for users from supportOrg.

  • applicationReviewSteps mapping The access request review step definitions and the reviewers associated with each review step. See Data Access Request Review Steps.

  • created timestamp When the TRE was created.

  • modified timestamp When the TRE was last modified.

Errors

  • ResourceNotFound

    • The TRE was not found.

  • PermissionDenied

    • The requesting user must be an authorized user, reviewer, or TRE admin of the TRE.

API method: /tre-xxxx/activate

Specification

Activates a TRE, transitioning it from draft or amending state to active state. On activation, pending inventory becomes active and the previously active inventory becomes inactive. A dispensal queue is created for the TRE. TRE admins are granted ADMIN access to the inventory projects. Authorized users are granted VIEW access to the showcase project when enableShowcase is true. The TRE robot user and the TRE working project are also provisioned or synchronized for TRE operations. The requesting user must be a TRE admin.

Inputs

None.

Outputs

  • id string ID of the TRE that was activated.

Errors

  • InvalidState

    • The TRE is not in draft or amending state.

    • The inventory or policies are not set.

    • The inventory has enableShowcase set to false, but enforceFullCohortSelection is not enabled.

    • The TRE uses a customizedRateCard but the billing org does not have a rate card set.

    • The TRE inventory has enableDataset or enableShowcase set to true, but the billing org does not have an Apollo license.

    • The TRE does not have at least one access request review step defined.

    • One or more review steps do not have at least one reviewer assigned.

  • ResourceNotFound

    • The TRE was not found.

  • PermissionDenied

    • The requesting user must be a TRE admin.

    • The requesting user must use a full-scope token.

API method: /tre-xxxx/deactivate

Specification

Deactivates a TRE, transitioning it from active state to amending state. This allows TRE admins to modify the TRE configuration before reactivating it. The requesting user must be a TRE admin.

Inputs

None.

Outputs

  • id string ID of the TRE that was deactivated.

Errors

  • InvalidState

    • The TRE is not in active state.

  • ResourceNotFound

    • The TRE was not found.

  • PermissionDenied

    • The requesting user must be a TRE admin.

    • The requesting user must use a full-scope token.

API method: /tre-xxxx/setFeatures

Specification

Sets feature flags for the TRE. TRE features are optional capability flags that modify TRE behavior beyond the configurable workspace policies. The requesting user must be a TRE admin.

Inputs

  • enforceFullCohortSelection boolean (optional) When true, every data access request submitted to this TRE must include the full participant cohort. Authorized users cannot access the Data Showcase or apply filters to define a participant population. Must be true before activation when the inventory has enableShowcase set to false. Can only be set to true in draft state. Cannot be disabled once enabled. In the UI, this setting is labeled Enforce Full Set Selection in the Data Showcase and Selection section of TRE settings.

Outputs

  • id string ID of the TRE that was modified.

Errors

  • ResourceNotFound

    • The TRE was not found.

  • PermissionDenied

    • The requesting user must be a TRE admin.

    • The requesting user must use a full-scope token.

  • InvalidState

    • The TRE is in active state.

    • enforceFullCohortSelection cannot be set or changed when the TRE is in amending state.

    • enforceFullCohortSelection cannot be disabled once enabled.

API method: /tre-xxxx/addAllowedProjects

Specification

Adds projects to the allowed projects list for the TRE. Projects in this list are exempt from the clone restriction that prevents cloning between TRE projects and non-TRE projects. The requesting user must be a TRE admin and must have at least VIEW access to each project being added.

Inputs

  • projects array of strings (required) Project IDs to add to the allowed projects list.

Outputs

  • id string ID of the TRE that was modified.

Errors

  • InvalidInput

    • projects is empty.

  • ResourceNotFound

    • The TRE was not found.

    • One or more projects in the list do not exist.

  • PermissionDenied

    • The requesting user must be a TRE admin.

    • The requesting user must use a full-scope token.

    • The requesting user must have at least VIEW access to each project being added.

API method: /tre-xxxx/removeAllowedProjects

Specification

Removes projects from the allowed projects list for the TRE. The requesting user must be a TRE admin and must have at least VIEW access to each project being removed.

Inputs

  • projects array of strings (required) Project IDs to remove from the allowed projects list.

Outputs

  • id string ID of the TRE that was modified.

Errors

  • InvalidInput

    • projects is empty.

  • ResourceNotFound

    • The TRE was not found.

    • One or more projects in the list do not exist.

  • PermissionDenied

    • The requesting user must be a TRE admin.

    • The requesting user must use a full-scope token.

    • The requesting user must have at least VIEW access to each project being removed.

Last updated

Was this helpful?