Data Access Requests

Learn about creating and managing Data Access Requests (TRE application objects) via the DNAnexus Platform API.

A Data Access Request is a request submitted by authorized users to access data provided by a Trusted Research Environment (TRE). In the API, Data Access Requests are represented as TRE application objects with IDs prefixed treApplication-. Authorized users or TRE reviewers create these access requests by specifying the requested data (cohort and fields), and each request goes through a configurable multi-step review workflow before data access is granted. In this reference, use "access request" for the user-facing concept and "application" only when citing API identifiers or field names.

If you want to manage data access requests in the Platform UI, see Submit a Data Access Request and Review Data Access Requests.

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

Data Access Request States

A data access request progresses through the following lifecycle states:

• "draft" The initial state after creation. The request owner or a reviewer can edit the access request details.

• "in-review" The access request has been submitted and is awaiting review. Individual review steps are resolved by assigned reviewers.

• "approved" All review steps have been approved. The request owner and collaborators can create projects and dispense data.

• "in-revision" One or more review steps have been rejected. The request owner can modify the access request and resubmit it for review.

Data Access Request Roles

Three roles interact with a data access request:

• Request Owner The user who owns the access request. In the API, the request owner is represented by the applicant field. The request owner can edit, submit, and delete the access request, and manage collaborators. By default, the request owner is the user who created the access request. A TRE reviewer can create an access request on behalf of another user by specifying the applicant field.

• Collaborator Users added by the request owner who gain view access to the access request details, view-only access to the cohort in the Cohort Browser, and access to projects created from the access request.

• Reviewer TRE reviewers assigned to specific review steps who can approve or reject the access request for their assigned steps. Reviewers can view all access request details, including review step decisions and approval history.

Review Decisions

Each review step must be independently resolved by at least one reviewer assigned to that step. The overall access request decision is determined by the following 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

When all steps are approved, the access request transitions to approved state. If any step is rejected, the access request transitions to in-revision state, allowing the request owner to revise and resubmit.

Cohort Metadata

Each Data Access Request can store one or more cohort metadata records that capture the cohort definitions used during data dispensal. A cohort metadata record contains a name, an optional description, and a details mapping that holds the cohort filter definition (for example, Cohort Browser filter criteria).

Cohort metadata records are managed independently from the access request through dedicated sub-resource methods:

• /treApplication-xxxx/createCohortMetadata

• /treApplication-xxxx/updateCohortMetadata

• /treApplication-xxxx/removeCohortMetadata

• /treApplication-xxxx/describeCohortMetadata

The resulting record IDs are referenced in the cohortMetadataRecords field when creating or updating an access request via /treApplication/new or /treApplication-xxxx/update.

The request owner and collaborators can create, update, and remove cohort metadata records. TRE reviewers have read-only access through the describe method.

Dispensal

When a Data Access Request reaches the approved state, the request owner and collaborators can create projects from the request. By default, creating a project from an approved request starts dispensal, which provisions the approved cohort and fields — including bulk files and tabular datasets — into the project. Dispensal can be disabled at project creation time by setting tre.dispense to false in /project/new.

Dispensed data is protected. Objects placed into a TRE project by the dispensal process cannot be deleted by any user. Attempting to remove dispensed objects returns a PermissionDenied error. Dispensed data is removed only when the entire project is destroyed. For more information about this restriction, see Non-Configurable Restrictions in the TRE API reference.

API Method Specifications

API Method: /treApplication/new

Specification

Creates a new Data Access Request (TRE application object) in draft state. The requesting user must be an authorized user of the TRE, or a TRE reviewer if specifying an applicant on behalf of another user. The TRE must be in active state.

Inputs

• title string (required) A short title for the access request, up to 256 characters.

• summary string (required) A detailed description of the access request, up to 5,000 characters.

• treId string (required) The ID of the TRE where the access request is being submitted.

• cohortMetadataRecords array of strings (required) A list of record IDs representing the cohort.

• fields array of strings (required) A list of field identifiers requested by the applicant.

• applicant string (optional) The user ID of the applicant. Only TRE reviewers can specify this field to create an access request on behalf of another authorized user. Defaults to the requesting user.

Outputs

• id string ID of the newly created TRE application object (for example, treApplication-B0FJgXy4Zg231jgbQ9zQ0003).

Errors

• InvalidInput

  • title exceeds 256 characters

  • summary exceeds 5,000 characters

  • applicant is specified but is not an authorized user of the TRE

• InvalidState

  • The TRE is not in active state

• ResourceNotFound

  • The TRE specified in treId was not found

  • One or more records in cohortMetadataRecords were not found

  • The applicant user was not found

• PermissionDenied

  • If applicant is specified, the requesting user must be a TRE reviewer

  • If applicant is not specified, the requesting user must be an authorized user of the TRE

  • The requesting user must use a full-scope token

API Method: /treApplication-xxxx/update

Specification

Updates an existing Data Access Request. The request must be in draft or in-revision state, and the TRE must be in active state. The requesting user must be the applicant or a TRE reviewer.

Inputs

• title string (optional) A short title for the access request, up to 256 characters.

• summary string (optional) A detailed description of the access request, up to 5,000 characters.

• cohortMetadataRecords array of strings (optional) A list of record IDs representing the cohort.

• fields array of strings (optional) A list of field identifiers requested by the applicant.

Outputs

• id string ID of the modified access request.

Errors

• InvalidInput

  • title exceeds 256 characters

  • summary exceeds 5,000 characters

• InvalidState

  • The TRE is not in active state

  • The access request is not in draft or in-revision state

• ResourceNotFound

  • The access request was not found

  • One or more records in cohortMetadataRecords were not found

• PermissionDenied

  • The requesting user must be the applicant or a TRE reviewer

API Method: /treApplication-xxxx/createCohortMetadata

Specification

Creates a new cohort metadata record for the access request. The record stores the cohort definition that the platform uses during data dispensal. The requesting user must be the applicant or a collaborator of the access request.

Inputs

• name string (required) A descriptive name for the cohort.

• description string (optional) A description of the cohort.

• details mapping (required) The cohort filter definition, for example, Cohort Browser filter criteria.

Outputs

• id string The record ID of the newly created cohort metadata record.

Errors

• InvalidInput

  • name is not provided or is empty

  • details is not provided or is empty

• ResourceNotFound

  • The access request was not found

• PermissionDenied

  • The requesting user must be the applicant or a collaborator of the access request

  • The requesting user must use a full-scope token

API Method: /treApplication-xxxx/updateCohortMetadata

Specification

Updates an existing cohort metadata record for the access request. The requesting user must be the applicant or a collaborator of the access request.

Inputs

• recordId string (required) The record ID of the cohort metadata record to update.

• name string (optional) A descriptive name for the cohort.

• description string (optional) A description of the cohort.

• details mapping (optional) The cohort filter definition.

Outputs

• id string The record ID of the updated cohort metadata record.

Errors

• ResourceNotFound

  • The access request was not found

  • The specified recordId was not found

• PermissionDenied

  • The requesting user must be the applicant or a collaborator of the access request

  • The requesting user must use a full-scope token

API Method: /treApplication-xxxx/removeCohortMetadata

Specification

Deletes a cohort metadata record from the access request. The requesting user must be the applicant or a collaborator of the access request.

Inputs

• recordId string (required) The record ID of the cohort metadata record to delete.

Outputs

• id string The record ID of the deleted cohort metadata record.

Errors

• ResourceNotFound

  • The access request was not found

  • The specified recordId was not found

• PermissionDenied

  • The requesting user must be the applicant or a collaborator of the access request

  • The requesting user must use a full-scope token

API Method: /treApplication-xxxx/describeCohortMetadata

Specification

Describes a cohort metadata record for the access request. The requesting user must be the applicant, a collaborator, or a TRE reviewer.

Inputs

• recordId string (required) The record ID of the cohort metadata record to describe.

Outputs

• id string The record ID.

• name string The name of the cohort.

• description string The description of the cohort.

• details mapping The cohort filter definition.

• created timestamp When the record was created.

• modified timestamp When the record was last modified.

Errors

• ResourceNotFound

  • The access request was not found

  • The specified recordId was not found

• PermissionDenied

  • The requesting user must be the applicant, a collaborator, or a TRE reviewer

  • The requesting user must use a full-scope token

API Method: /treApplication-xxxx/submit

Specification

Submits an access request for review. The access request must be in draft or in-revision state, and the TRE must be in active state. On submission, all review step statuses are reset to in-review, and submission actions are recorded in approvalHistory for each review step. Email notifications are sent to the assigned reviewers, and a submission confirmation is sent to the submitting user. The requesting user must be the applicant or a TRE reviewer.

Inputs

• message string (optional) A message to include with the submission, up to 1,000 characters.

Outputs

• id string ID of the submitted access request.

Errors

• InvalidInput

  • message exceeds 1,000 characters

• InvalidState

  • The access request is not in draft or in-revision state

  • The TRE is not in active state

• ResourceNotFound

  • The access request was not found

• PermissionDenied

  • The requesting user must be the applicant or a TRE reviewer

  • The requesting user must use a full-scope token

API Method: /treApplication-xxxx/approve

Specification

Approves a specific review step in the access request approval workflow. The access request must be in in-review state and the TRE must be in active state. The step decision is recorded in approvalHistory, and a confirmation email is sent to the current reviewers. If all review steps are approved after this action, the access request transitions to approved state and the applicant is notified. If the TRE uses a customized rate card, a wallet is created for the applicant and collaborators on approval. The requesting user must be a reviewer assigned to the specified review step.

Inputs

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

• message string (optional) A message to include with the approval decision, up to 1,000 characters.

Outputs

• id string ID of the approved access request.

Errors

• InvalidInput

  • reviewStepId does not match a valid review step

  • message exceeds 1,000 characters

• InvalidState

  • The access request is not in in-review state

  • The TRE is not in active state

• ResourceNotFound

  • The access request was not found

• PermissionDenied

  • The requesting user must be a reviewer assigned to the specified review step

  • The requesting user must use a full-scope token

API Method: /treApplication-xxxx/reject

Specification

Rejects a specific review step in the access request approval workflow. The access request must be in in-review state. The step decision is recorded in approvalHistory, and a confirmation email is sent to the current reviewers. If any review step is rejected, the access request transitions to in-revision state, allowing the applicant to modify and resubmit the access request. The requesting user must be a reviewer assigned to the specified review step.

Inputs

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

• message string (optional) A message to include with the rejection decision, up to 1,000 characters.

Outputs

• id string ID of the rejected access request.

Errors

• InvalidInput

  • reviewStepId does not match a valid review step

  • message exceeds 1,000 characters

• InvalidState

  • The access request is not in in-review state

• ResourceNotFound

  • The access request was not found

• PermissionDenied

  • The requesting user must be a reviewer assigned to the specified review step

  • The requesting user must use a full-scope token

API Method: /treApplication-xxxx/delete

Specification

Deletes an access request. The access request can only be deleted if there are no projects associated with it, and the access request is hard deleted. If the TRE uses a customized rate card and the access request is in approved state, the associated wallet (org) is destroyed. The requesting user must be the applicant.

Inputs

None.

Outputs

• id string ID of the deleted access request.

Errors

• InvalidState

  • The access request has projects associated with it and cannot be deleted

• ResourceNotFound

  • The access request was not found

• PermissionDenied

  • The requesting user must be the applicant

  • The requesting user must use a full-scope token

API Method: /treApplication-xxxx/describe

Specification

Describes a Data Access Request. The output depends on the requesting user's role. Applicants and collaborators see the default access request fields. TRE reviewers see additional review step details and approval history.

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 access request (applicant, collaborators, and reviewers):

• id string The access request ID.

• title string The title of the access request.

• summary string The detailed description of the access request.

• cohortMetadataRecords array of strings The record IDs representing the cohort.

• cohortAccess string The level of access the requesting user has to the cohort. Collaborators and reviewers have "VIEW" access. The applicant has "EDIT" access.

  • Must be one of "VIEW" or "EDIT".

• fields array of strings The field identifiers requested in the access request.

• treId string The TRE ID.

• state string The current state of the access request.

  • Must be one of "draft", "in-review", "approved", or "in-revision".

• applicant string The user ID of the applicant.

• collaborators array of strings The user IDs of collaborators.

• overallReviewDecision string The aggregate review decision across all steps. See Review Decisions.

  • Must be one of "Approved", "Pending", or "Rejected".

• messages array of mappings Messages from the applicant and reviewers.

• createdBy string The user ID of the access request creator.

• created timestamp When the access request was created.

• modifiedBy string The user ID of the user who last modified the access request.

• modified timestamp When the access request was last modified.

The following fields are available only to TRE reviewers:

• approvals array of mappings The current status of each review step, including the review step ID and its state.

• approvalHistory array of mappings A complete history of actions taken on the access request, including submissions, approvals, and rejections with timestamps and user IDs.

Errors

• ResourceNotFound

  • The access request was not found

• PermissionDenied

  • The requesting user must be the applicant, a collaborator, or a TRE reviewer

  • The requesting user must use a full-scope token

API Method: /treApplication-xxxx/addCollaborators

Specification

Adds collaborators to an access request. Collaborators gain view access to the access request details, view-only access to the cohort in the Cohort Browser, and can create projects from the approved access request. The requesting user must be the applicant. Collaborators can be added in any access request state. If the TRE uses a customized rate card and the access request has an associated wallet, new collaborators are added as wallet members.

Inputs

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

  • The total number of collaborators must not exceed 100.

  • Each collaborator must be an authorized user of the TRE (or a member of an authorized org, or any user if the TRE authorized users include PUBLIC).

Outputs

• id string ID of the modified access request.

Errors

• InvalidInput

  • users is not provided or the list is empty

  • Adding these users would exceed the limit of 100 collaborators

  • One or more users are not authorized users of the TRE

• ResourceNotFound

  • The access request was not found

  • One or more users in the list do not exist

• PermissionDenied

  • The requesting user must be the applicant

  • The requesting user must use a full-scope token

API Method: /treApplication-xxxx/removeCollaborators

Specification

Removes collaborators from an access request. Removed collaborators are removed from all projects associated with the access request, regardless of their role in those projects. This includes cases where the removed user is the only admin or only member of a project. If the TRE uses a customized rate card, removed collaborators are also removed from the associated wallet (org). The requesting user must be the applicant.

Inputs

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

Outputs

• id string ID of the modified access request.

Errors

• InvalidInput

  • users is not provided or the list is empty

• ResourceNotFound

  • The access request was not found

  • One or more users in the list do not exist

• PermissionDenied

  • The requesting user must be the applicant

  • The requesting user must use a full-scope token