Introduction

SafeInsights has three applications (Management, Setup, and Trusted Output) that communicate with each other and with your Secure Enclave. This page documents the API structure, authorization schema and other information to make these work together.

Sample Network Addresses

Applications in the OpenStax Member Enclave is assigned the following domains & paths:

• https://app.safeinsights.org/ will load the Management App and serve as the the main entry point
• The OpenStax member start page for Researchers to request studies from will be linked from the OpenStax member page in the Knowledge Base will be: app.safeinsights.org/researcher/study/request/openstax

Study Proposal Statuses

Studies will have a status property (all set by the Management App)

• INITIATED: Researcher has created study proposal AND hasn’t submitted it for Member review
• PENDING-REVIEW: Researcher has submitted study proposal AND awaiting Member review
• APPROVED: Member has approved study proposal proposal
• REJECTED: Member has soft rejected proposal
• ARCHIVED: study has been archived, no further activity can be taken

There will also be

objects that will belong to studies. An execution will be created immediately after a study is approved.

Study Code Run (Jobs) Statuses

Each study code run will have a status of (i.e. you can’t have multiple statuses per run):

• CODE-INITIATED: Set by Management App (MA). Records initial state when a study draft is created. No researcher code has been pushed to the container, and the run record will not appear in APIs.
• CODE-SUBMITTED: Set by MA. Researcher code is present and awaiting review and approval by Member, record will not appear in APIs.
• CODE-REJECTED: Set by MA. Member has rejected the initial code.
• CODE-APPROVED: Set by MA. Code has been approved by Member, record appears in API for Setup App.
• JOB-PACKAGING: Set by the MA. Once the code is approved, the BMA packages it for the Setup App to pick up.
• JOB-READY: Set by the MA. Code is ready and waiting to be picked up by the Setup App (could take a minute to a few hours depending on enclave setup)
• JOB-PROVISIONING: Set by Setup App. Setup App has picked up the code (package) and is preparing to run it against the enclave data.
• JOB-RUNNING: Set by Research Container. Code is running inside the enclave.
• JOB-ERRORED: Set by Research Container via Trusted Output App & Setup App. TOA will send an error if code fails (e.g. data source is unavailable, expected version or schema in code does not match with the actual schema, if a bug causes a crash); Setup App will send an error if the Research Container doesn't start or has an issue starting.
• RESULTS-PENDING-REVIEW: Set by MA upon receiving encrypted results. Upon job completion and successful storing of encrypted results from TOA - ready for the Member to review the results.
• RESULTS-REJECTED: Set by MA. Member has rejected the job output.
• RESULTS-APPROVED: Set by MA. Member has approved job output, results are decrypted and sent to Researcher.

API definitions for Management App

APIs will use camelCase for the properties. All requests to the API MUST have a Authorization header with a JSON Web Token bearer as described below in API Security. The Management app is the provider of this API, it will be called by the Setup App as it polls.

GET /api/studies/ready

Returns an object with a “jobs” property. The jobs property will contain an array containing all studies with status of in-queue and in-progress.

Returns an array of:

jobId	uuid	Id of the job request, unique to this job
studyId	uuid	Id of the study, each study may have MULTIPLE jobs
requestedAt	timestamp	When the study was approved
title	text	Study title
status	text	Execution status as described above, e.g., JOB-READY
dataSources	[‘highlights’, ‘event_capture’]	Name of the dataset(s)
containerLocation	url without scheme	url to ECR, including tag
outputMimeType	Mime type of output	Currently, only text/csv is supported.

This will be called by the Setup App to deliver job start notices and by the Trusted Output App to deliver results.

GET /api/job/<jobId>/keys

jobId is uuid, obtained from /api/studies/ready. Called by the Trusted Output App, returns a list of all the Member’s public keys that are reviewers for the study that the job belongs to (also known as the public key from the Member Reviewer Keypair).

{
   keys: array of { 
      fingerprint: <SHA-256 fingerprint of key>, 
      key: PEM encoded RSA public key 
   }
}

PUT /api/job/<jobId>

jobId is uuid, obtained from /api/studies/ready result set

{
   status: JOB-PROVISIONING | JOB-ERRORED | JOB-RUNNING | RESULTS-PENDING-REVIEW | RESULTS-REJECTED | RESULTS-APPROVED
   message: a short string describing the status, limited to 256 characters

}

POST /api/job/<jobId>/results

jobId is uuid, obtained from /api/studies/ready result set Request payload will be a multipart/form-data file, with same restrictions as Research Container posting to TOA (single CSV file).

The Trusted Output app will obtain the file from the Researcher code (see section below) It will post it to the Management App’s /results url when approved.

Response will be status 200 with empty body to indicate update success.

API Security

All requests from enclave apps (Setup App, TOA) will be accompanied by an “Authorization” header whose value is a Bear token. The token will be a JSON Web Token (JWT) that is RSA signed and encrypted and contain the following standard fields:

• iss
  (Issuer): your organization
• sub
  (Subject): safe-insights
• exp
  (Expiration Time): a timestamp no further than 15 minutes in the future
• nbf
  (Not Before): a timestamp in the past

The enclave member will generate a Member Enclave Management key pair pair using commands that we document. They will provide the public key to a trusted SI representative who will input it to the management app as part of the enclave configuration. Doing so is secure because a public key is not sensitive and intended for public dissemination.

The management app will store the public RSA key, and the enclave apps will store the public/private key and use those to create the JWT.

When access to an API endpoint is rejected, an appropriate http status will be set such as 401 and a JSON object with an “error” property describing the error will be returned.

Researcher Code Requirements

Currently, we only support Researcher code written in R and built into a container that is based on a single known and approved base image. The container MUST be built to run on platform “linux/amd64”.

The Researcher code will report its results using a url read from a key in process’s environment named

(currently ). The code will perform a POST to that url with an encrypt type of multipart/form-data (standard file upload).

While multipart/form-data does support multiple files, only a single file named “results.csv” will be included in the request.