AMPALS Portal - DAR and Approval Integration
Introduction
The ALS Knowledge Portal aggregates content from multiple data repositories, enabling researchers to browse, search, query, and select data from multiple platforms for analysis.
Currently, users who want to access data hosted by the Critical Path Institute must submit a data access request through https://fair.dap.c-path.org/. After a request is submitted, the ALS Knowledge Portal calls the FAIR API to check the request approval status. Once approved, the user signs in to RDCA-DAP and accesses the data through their approved workspace.
Purpose
The purpose of this design is to improve the user experience by allowing users to create data access requests directly from the ALS Knowledge Portal instead of signing in to RDCA-DAP. The ALS Knowledge Portal will display the request status. Once a request is approved, users will go to RDCA-DAP to download or query their approved data within the approved workspace.
Data
The C-Path datasets displayed on the ALS Knowledge Portal are governed by a contractual agreement with the Critical Path Institute. Any modifications—such as adding or removing datasets—would require changes to this contract. Currently, only 5 RDCA-DAP datasets are listed on the Portal, and users can submit data access requests exclusively for these 5 datasets.
@Ann Novakowski Should the dataset tables/dictionaries and workspace location data be pre-fetched — either via a script or manually, similar to how other metadata is collected — or retrieved just-in-time via an API call?
Per a Teams conversation: "The dictionaries are relatively stable, with updates (additions, removals, or changes) occurring on the order of months. There are also only two workspace locations."
Access Requirement
A new CPathManagedAccessRequirement will be introduced for C-Path-hosted data. This class will extend JsonSchemaAccessRequirement. The ACT will be responsible for registering the associated JSON Schema for this Access Requirement.
@Ann Novakowski How will ACT obtain the JSON Schema, and how will schema modifications be detected so that the associated AccessRequirement can be updated accordingly? A question has been raised with C-Path regarding whether an API exists for retrieving the JSON Schema — this is currently pending a response.
Data Submission
In the current system, only one OPEN submission is allowed at a time. After a submission is approved, if the same user creates another submission for the same AR—as both the accessor and submitter—the existing access approval is updated. In effect, there is a single approval record.
To keep C-Path DAR in sync with the current system, we need to determine how it should align with the existing access request model. There are two possible approaches. @Ann Novakowski, we need your input here.
Should there be one DAR per AR per dataset, with the user receiving access by default to all tables/directories under that dataset?
Should there be one AR per table/directory?
In the current data submission flow, a user can create a data submission request and add other requesters, as shown below. For C-Path DARs, approval is handled by C-Path. When a DAR is created, we do not have a way to determine whether any additional users added to the DAR have been approved. We can retrieve the DAR status only for the requester, so the “Data requesters” section shown in the image below is not applicable to C-Path DARs.
How to create a DAR
When a C-Path-hosted dataset is displayed as restricted in the UI, the user can select the dataset to view the new access requirement, complete the DAR, and submit the request.
Alternatively, the user can add the dataset to the download cart.
From the download cart, under “Access action required,” the new access requirement and DAR will be shown for the selected dataset. @Ann Novakowski we need your input.
The data access request for C-path data is combination of information filled by user and make just in time choices. This request can not be completed with only with the Json Schema attached to the AR.
The request is technically divided into 2 sections. first section should include information about dataset, existing workspaces and terms which is dynamically selected by user.
In second section the JSON Schema attached to the AR will be presented to the user as a multi-step form(information about Project, new workspace, about). The user will complete the required fields and submit their data access request (DAR).
This DAR will not be reviewed by ACT — instead, it will be approved or rejected by C-Path approvers.
Once the DAR is submitted user click on status field it should show DAR and its status.
API Design Workflow
Data Access Request Initiation — When a user selects restricted C-Path data, they are redirected to submit a data access request. Ampals calls the following endpoint:
GET /repo/v1/entity/68884387/accessRequirement
The API returns a CPathManagedAccessRequirement, which includes an attached JSON schema. This schema is rendered as a form that the user must complete.
Retrieving Dynamic Data for the DAR — Ampals also calls a new endpoint to fetch dynamic data associated with the Data Access Request:
GET /repo/v1/dataset/{datasetCode}/dataAccessOptions
This endpoint orchestrates a sequence of FAIR API calls to gather all required information:
a. Token Exchange — Calls the C-Path authentication endpoint (https://gateway.westeurope.dap.c-path.org/authenticate) to perform a token exchange. This returns an access token for the FAIR API, valid for 5 minutes. All subsequent calls use this token.
b. Retrieve Data Dictionaries — Fetches the available dictionaries for the selected dataset:GET /api/datasets/{datasetCode}/dictionaries?page=1&dataExists=false
c. Retrieve Workspace Locations — Fetches the available workspace locations for the selected dataset:GET /api/datasets/{datasetCode}/workspaces-locations/
d. Retrieve Existing Workspaces (West Europe) — Lists workspaces already provisioned in the West Europe region:GET /api/datasets/{datasetCode}/workspaces/?location=westeurope
e. Retrieve Existing Workspaces (North Europe) — Lists workspaces already provisioned in the North Europe region:GET /api/datasets/{datasetCode}/workspaces/?location=northeurope
Response:
FairDatasetRequestOptions.json
{
"description": "Aggregated options for building an RDCA-DAP data access request for a dataset. Assembled from the FAIR dictionaries, workspace-locations, and per-location workspaces endpoints.",
"properties": {
"datasetCode": { "type": "string" },
"dictionaries": { "type": "array", "items": { "$ref": "org.sagebionetworks.repo.model.fair.FairDictionary" }, "description": "Available data dictionaries; the user's selection becomes cohort clauses in the submit
request." },
"workspaceLocations": { "type": "array", "items": { "$ref": "org.sagebionetworks.repo.model.fair.FairWorkspaceLocation" }, "description": "Available hub locations, each with its workspaces." }
}
}
FairDictionary.json
{
"description": "A data dictionary available for a dataset (from GET /datasets/{code}/dictionaries).",
"properties": {
"id": { "type": "integer" },
"code": { "type": "string", "description": "Used as cohort clause dictionary.code in the submit request." },
"name": { "type": "string" },
"description": { "type": "string" },
"primary": { "type": "boolean" },
"createdOn": { "type": "string", "format": "date-time" },
"modifiedOn": { "type": "string", "format": "date-time" }
}
}
FairWorkspaceLocation.json
{
"description": "A hub location where a workspace can be provisioned (from GET /datasets/{code}/workspaces-locations), with the workspaces available at that location.",
"properties": {
"id": { "type": "integer" },
"value": { "type": "string", "description": "Location code, e.g. 'westeurope'. Used to query workspaces for this location." },
"description": { "type": "string" },
"organisation": { "type": "string" },
"regionalDisplayName":{ "type": "string" },
"workspaces": { "type": "array", "items": { "$ref": "org.sagebionetworks.repo.model.fair.FairWorkspace" } }
}
}
FairWorkspace.json
{
"description": "A workspace available at a location (from GET /datasets/{code}/workspaces?location=...).",
"properties": {
"uuid": { "type": "string", "description": "Selected as workspace_uuid in the submit request." },
"name": { "type": "string" },
"url": { "type": "string" },
"location": { "type": "string" },
"requested": { "type": "boolean" },
"requestForm": { "type": "string", "description": "Markdown summary of the request that produced this workspace." },
"reference": { "type": "string" },
"requestedBefore": { "type": "boolean" },
"compatibility": { "type": "array", "items": { "type": "string" }, "description": "Empty in samples; item shape TBD with FAIR." }
}
}
Using the APIs described above, we can populate all the required information for the Destination section, as illustrated in the screenshot. The "Choose" tab is not needed in our case, since form portal users can only request access to the five predefined datasets. The UI can render the various sections of the access request form by combining the response object from the above API calls with the JSON schema defined in the Access Requirement.
Submitting a Data Access Request (DAR) to C-Path
In the current Access Requirement flow, a user can only have one mutable DataAccessRequest at a time, along with one open submission (which is an immutable snapshot created at the time of submission). Approval is keyed by the Access Requirement, accessor, version, and submitter.
For C-Path data, however, the approval process differs — it is not handled by the ACT. Instead, the approval status is determined through a FAIR API call, making the standard data access submission and approval flow irrelevant
The submission process works as follows:
a. Create the DAR — When a user submits a Data Access Request for C-Path data, a DataAccessRequest is created via a new endpoint:POST /repo/v1/dataAccessRequest/{requestId}/CPathDar
The Portal sends a CreateCPathDarRequest body carrying both the schema-validated answers and the dynamic selections.
CreateCPathDarRequest.json
{
"description": "Body the Portal sends to submit a C-Path DAR. Combines the schema-validated form answers (static) with the just-in-time selections made from FairDatasetRequestOptions (dynamic).",
"properties": {
"accessRequirement": { "$ref": "org.sagebionetworks.repo.model.AccessRequirementReference" },
"submissionData": { "type": "object", "description": "Form answers, validated against the AR's JSON Schema." },
"workspaceRequested": { "type": "boolean" },
"workspaceUuid": { "type": "string", "description": "Selected existing workspace (from options). Used when workspaceRequested = false." },
"transferType": { "type": "string" },
"terms": { "type": "boolean", "description": "User accepted the terms (section 1)." },
"selectedDictionaryCodes": { "type": "array", "items": { "type": "string" }, "description": "FairDictionary.codes chosen for the cohort." },
"cohortName": { "type": "string" },
"attachments": { "type": "array", "items": { "type": "string" } }
}
}
b. Assemble the FAIR request payload — Synapse validates submissionData against the AR's JSON Schema, then maps the CreateCPathDarRequest into a CreateFairRequest:
FAIR payload fields | source |
|---|---|
name | submissionData.name |
fields | submissionData minus name and code; if workspaceRequested = true, merge the workspace-form answers in |
workspace_requested | CreateCPathDarRequest.workspaceRequested |
workspace_uuid | CreateCPathDarRequest.workspaceUuid |
transfer_type | CreateCPathDarRequest.transferType |
terms | CreateCPathDarRequest.terms |
attachments | need to check with Cpath |
cohort.name | CreateCPathDarRequest.cohortName |
cohort.queries[0].name | CreateCPathDarRequest.cohortQuery.name |
cohort.queries[0].clauses[] | one clause per selected dictionary |
c. Token Exchange — A token exchange is performed via the C-Path authentication endpoint (https://gateway.westeurope.dap.c-path.org/authenticate) to obtain a FAIR API access token.
d. Submit the Request to FAIR — Using the FAIR token, the request is submitted via:POST https://fair.dap.c-path.org/api/requests/
The response returns a request code along with the current approval status which is pending.
e Track Approval Status — The returned request code is associated with the DataAccessRequest and is used to query the approval status going forward.
Retrieving Access Approval Status from C-Path
When
POST /repo/v1/restrictionInformationis called for aEntityobject, Synapse will determined it is a C-PATH entity or not. If it is C-path entity it perform the following actions:
a. Resolve the Dataset — Retrieve the object ID (which corresponds to the datasetId) and use it to look up the associated DataAccessRequest, which contains the FAIR request code needed to check access
b. No Existing Request — If no DataAccessRequest has been submitted yet, the RestrictionInformationResponse.hasUnmetAccessRequirement field will be set to true.
c. Existing Request — Check Approval Status — If a DataAccessRequest exists, perform a token exchange via the C-Path authentication endpoint (https://gateway.westeurope.dap.c-path.org/authenticate) to obtain a FAIR API token, then queryGET https://fair.dap.c-path.org/api/requests/{code} for approval status
Post-Approval — Displaying Unlocked Data
Once the data access request is approved, the UI should display the dataset as unlocked. When the user hovers over it, a tooltip should appear with the message: "Log in to RDCA-DAP to analyze the data." ( @Ann Novakowski: Should we include a direct link to C-Path (or any other information) to guide the user on next steps?)
Json Schema (Attached to AR and use to fill static information from user)
{
"$id": "org.sagebionetworks.ampals-rdca-access-request-1.0.0",
"type": "object",
"properties": {
"code": { "type": "string", "maxLength": 256, "description": "Request ID; allocated by RDCA if blank." },
"name": { "type": "string", "maxLength": 256 },
"full_name": { "type": "string", "maxLength": 256 },
"organization": { "type": "string", "maxLength": 256 },
"org_country": { "type": "string", "maxLength": 256 },
"org_state": { "type": "string", "maxLength": 256 },
"org_address": { "type": "string", "maxLength": 4096 },
"sector": { "type": "string", "enum": ["Academia", "Pharma", "Non-profit", "Government", "Other"] },
"dept": { "type": "string", "maxLength": 256 },
"position": { "type": "string", "enum": ["Research", "Faculty", "Postdoc", "Other"] },
"education": { "type": "string", "maxLength": 256 },
"websites": { "type": "string", "maxLength": 4096 },
"email": { "type": "string", "maxLength": 256 },
"phone_number": { "type": "string", "maxLength": 64 },
"user_country": { "type": "string", "maxLength": 256 },
"user_state": { "type": "string", "maxLength": 256 },
"project_name": { "type": "string", "maxLength": 250 },
"project_synopsis": { "type": "string", "maxLength": 4096 },
"results_pub_intent": { "type": "string", "maxLength": 4096 },
"curation_req": { "type": "string", "enum": ["Raw", "Curated OMOP", "Curated SDTM"] },
"principal_investigator":{ "type": "string", "maxLength": 250 },
"check_PI": { "type": "boolean", "const": true },
"additional_user_access":{ "type": "string", "maxLength": 4096 },
"check_users": { "type": "boolean", "const": true },
"project_signatories": { "type": "string", "maxLength": 4096 },
"check_sig": { "type": "boolean", "const": true },
"project_end_date": { "type": "string", "format": "date" }
},
"required": [
"name", "full_name", "organization", "org_country", "org_address", "sector",
"dept", "position", "email", "phone_number", "user_country",
"project_name", "project_synopsis", "results_pub_intent", "principal_investigator",
"check_PI", "additional_user_access", "check_users", "project_signatories",
"check_sig", "project_end_date"
]
}
FormTemplate
{
"name": "AMP-ALS RDCA Access Request",
"schema$id": "org.sagebionetworks.ampals-rdca-access-request-1.0.0",
"steps": [
{
"title": "About",
"description": "Applicant Affiliation",
"fields": [
{ "schemaPath": "/code", "uiDefinition": { "ui:placeholder": "Enter a unique ID or leave blank and we will allocate one for you" } },
{ "schemaPath": "/name", "uiDefinition": { "ui:placeholder": "Name this request" } },
{ "schemaPath": "/full_name", "uiDefinition": { "ui:placeholder": "Your first and last name" } },
{ "schemaPath": "/organization", "uiDefinition": { "ui:placeholder": "Add the name of your institution or organization" } },
{ "schemaPath": "/org_country", "uiDefinition": { "ui:placeholder": "Enter the country of your institution or organization" } },
{ "schemaPath": "/org_state", "uiDefinition": { "ui:placeholder": "Enter the state or region of your institution or organization" } },
{ "schemaPath": "/org_address", "uiDefinition": { "ui:widget": "textarea", "ui:placeholder": "Add the street address of your institution or organization" } },
{ "schemaPath": "/sector", "uiDefinition": { "ui:widget": "select", "ui:placeholder": "The sector of the institution or organization" } },
{ "schemaPath": "/dept", "uiDefinition": { "ui:placeholder": "Add the name of your department" } },
{ "schemaPath": "/position", "uiDefinition": { "ui:widget": "select", "ui:placeholder": "Your position or role" } },
{ "schemaPath": "/education", "uiDefinition": { "ui:placeholder": "Degree(s) and respective college or university" } },
{ "schemaPath": "/websites", "uiDefinition": { "ui:widget": "textarea" } },
{ "schemaPath": "/email", "uiDefinition": { "ui:placeholder": "Add your institutional email address" } },
{ "schemaPath": "/phone_number", "uiDefinition": { "ui:widget": "PhoneWidget", "ui:options": { "country": "us", "preferredCountries": ["us", "gb"] } } },
{ "schemaPath": "/user_country", "uiDefinition": { "ui:placeholder": "Enter your country of residence" } },
{ "schemaPath": "/user_state", "uiDefinition": { "ui:placeholder": "Enter your state or region of residence" } }
]
},
{
"title": "Project",
"fields": [
{ "schemaPath": "/project_name", "uiDefinition": { "ui:placeholder": "Add the title of the research plan or study to be made publicly available" } },
{ "schemaPath": "/project_synopsis", "uiDefinition": { "ui:widget": "textarea", "ui:placeholder": "Describe goals, expected milestones, and how RDCA-DAP supports your goals" } },
{ "schemaPath": "/results_pub_intent", "uiDefinition": { "ui:widget": "textarea", "ui:placeholder": "Describe how results will be used and any publication intentions" } },
{ "schemaPath": "/curation_req", "uiDefinition": { "ui:widget": "select", "ui:placeholder": "The preferred format of the data" } },
{ "schemaPath": "/principal_investigator", "uiDefinition": { "ui:placeholder": "Name and email for the PI (if different than the requester)" } },
{ "schemaPath": "/check_PI", "uiDefinition": { "ui:widget": "checkbox" } },
{ "schemaPath": "/additional_user_access", "uiDefinition": { "ui:widget": "textarea", "ui:placeholder": "List any additional users who will need access (name, title, and email)" } },
{ "schemaPath": "/check_users", "uiDefinition": { "ui:widget": "checkbox" } },
{ "schemaPath": "/project_signatories", "uiDefinition": { "ui:widget": "textarea", "ui:placeholder": "Institutional authorized signatory(s) (name, title, and email)" } },
{ "schemaPath": "/check_sig", "uiDefinition": { "ui:widget": "checkbox" } },
{ "schemaPath": "/project_end_date", "uiDefinition": { "ui:widget": "date", "ui:placeholder": "Anticipated end date of your research or study" } }
]
},
{
"title": "Request a workspace",
"description": "Details of the workspace being requested:",
"fields": [
{ "schemaPath": "/project_name", "uiDefinition": { "ui:placeholder": "Add the name of the project and project ID if applicable" } },
{ "schemaPath": "/project_description", "uiDefinition": { "ui:widget": "textarea" } },
{ "schemaPath": "/emails", "uiDefinition": { "ui:widget": "textarea", "ui:placeholder": "Provide email addresses of other users who should be invited to the workspace" } },
{ "schemaPath": "/region", "uiDefinition": { "ui:widget": "select", "ui:placeholder": "Select Hub location..." } },
{ "schemaPath": "/windows_vm", "uiDefinition": { "ui:widget": "checkbox", "ui:title": "Windows Virtual Machine", "ui:help": "Do you require a virtual machine?" } },
{ "schemaPath": "/linux_vm", "uiDefinition": { "ui:widget": "checkbox", "ui:title": "Linux Virtual Machine" } },
{ "schemaPath": "/data_science", "uiDefinition": { "ui:widget": "checkbox", "ui:title": "Data science - general", "ui:help": "What is your area of interest? Check all that apply." } },
{ "schemaPath": "/bio_informatics", "uiDefinition": { "ui:widget": "checkbox", "ui:title": "Bioinformatics/BioStatistics" } },
{ "schemaPath": "/maths", "uiDefinition": { "ui:widget": "checkbox", "ui:title": "Mathematics/Statistics" } },
{ "schemaPath": "/ai", "uiDefinition": { "ui:widget": "checkbox", "ui:title": "AI/Machine Learning" } }
]
}
]
}
Second Approach — Standalone External Data Access Feature (decoupled from Access Requirement)
This approach supersedes the first. On First review, coupling C-Path external approval into Synapse's AccessRequirement / AccessApproval / restrictionInformation engine was rejected: an external, identity-unverified approval must never drive Synapse access control. The design below is a standalone feature that is NOT coupled to AccessRequirement, AccessApproval, DataAccessSubmission, or restrictionInformation.
Approach
Users may submit multiple Data Access Requests (DARs) for C-Path datasets. In the initial release, the ALS Knowledge Portal will display the status of the user's most recent DAR for a given dataset; users can visit RDCA-DAP directly to view their full DAR history. Once a DAR is approved, the user must log in to RDCA-DAP to analyze the data in their approved workspace.
This introduces a new feature for tracking DARs submitted to third-party systems that host restricted data outside of Synapse. FAIR serves as the source of truth for form definitions and DAR status; Prtal will handles token exchange, aggregation and response shaping.
Eligibility:
A user is eligible to submit a DAR if they have linked their ALS Knowledge Portal account with RDCA-DAP. In practice, this means the user must have logged in to RDCA-DAP at least once prior to creating a DAR.
Form Steps & Grouping Strategy
Tabs: Destination (choose dictionaries + choose/create workspace) → Workspace (only if creating a new one) → Project → About → Complete (accept terms). Form data is loaded lazily per step (NOT one bootstrap) because a user may linger on Destination, never create a workspace, or abandon the flow.
High level Design Diagram
FAIR API endpoints
Description | FAIR Endpint | Request Body | Response Body |
|---|---|---|---|
Request page opens (Destination tab) | GET https://fair.dap.c-path.org/api/datasets/{Dataset code}/dictionaries?page=1&dataExists=false. GET https://fair.dap.c-path.org/api/datasets/{Dataset code}/workspaces-locations/ GET https://fair.dap.c-path.org/api/datasets/{Dataset code}/workspaces/?location=westeurope | None | "items": [
"items": [
items": [ |
Request for existing workspace per location | GET https://fair.dap.c-path.org/api/datasets/{Dataset code}/workspaces/?location=location | None | items": [ |
User selects "create new workspace" | GET https://fair.dap.c-path.org/api/workspaces-forms/workspace_request | None | "name": "Request a workspace", }` |
User advances to Project / About tab | GET https://fair.dap.c-path.org/api/workflows/rdca_access_request | None | { |
Major Security Concern: Access Requirement (AR) Coupling
The current design attempts to map C-Path external approval status directly to a local Synapse
AccessRequirement(AR). Because Synapse relies on a backend service account token exchange rather than OAuth/identity federation, Synapse cannot cryptographically verify that SynapseUser Ais authorized to submit requests on behalf of RDCA-DAPUser B.Security Vulnerability
If a malicious user submits false identity details in the static DAR form, C-Path’s resulting approval will cause Synapse to set
hasUnmetAccessRequirement = false. This creates a severe security vulnerability where an unauthorized user can unlock and access Synapse-hosted data gated under that same AR within Synapse—completely bypassing Synapse's access control boundaries.Recommendation
We should decouple C-Path external request tracking from Synapse’s internal
AccessRequirementengine, or require a one-time OAuth identity linking step with RDCA-DAP before allowing DAR submission.