This articles walks you through the steps required to onboard to the BCL API, validate your integration in the staging environment, and launch in production.

Onboarding Checklist

Create a Service Account

Create a service account for API access and share the details with us here: BCL - API Onboarding
Register User Accounts

Provide your project and user details here: BCL - Users/Actors

Once this information is received, the BCL Support team will:

Create your project
Add registered users
Provide your project key

Authenticate your Service Account

After your service account is created and associated with your project, authenticate it to begin making API requests.

Authenticate Your Service Account

Staging: End-to-End Workflow

We strongly recommend completing an end-to-end test in the staging environment before moving to production. This includes:

Retrieving test metadata
Creating an order
Retrieving test reports and deliverable files

Before You Begin

Please note the following requirements:

Project Key required: Each order must include a project key recognized by the BCL development team.
Separate project keys will be provided for staging and production.
Actor-Email Header required: Some endpoints require an Actor-Email header. The value must be the email address of the user (“actor”) making the request. The API validates this email against our database to confirm the user:
- Has an active account
- Has sufficient permissions

Example (Staging)

curl -H "Authorization: Bearer {token}" \
    -H "Actor-Email: person@yourdomain.com" \
    https://gpo-staging.broadinstitute.org/auth

Step 1: Retrieve Test Endpoint

Use this endpoint to retrieve all required metadata for a given test:

https://gpo-staging.broadinstitute.org/api/redoc#tag/Catalogs/operation/get_test_metadata_details_api_catalog_metadata_project__project_key__test__test_code__get

Example code.

Step 2: Create an Order

Create an order in the staging environment using the following endpoint:

https://gpo-staging.broadinstitute.org/api/redoc#tag/Orders-and-Samples/operation/post_order_api_order_post

Example code.

Optional: Validate an Order

Before submitting an order, you may validate the payload to ensure all required fields and values are correct:

https://gpo-staging.broadinstitute.org/api/redoc#tag/Orders-and-Samples/operation/validate_order_api_order_validate_post

Step 3: Run End-to-End Tool

Run the end-to-end tool in the staging environment to move the order into a completed status.

Step 4: Retrieve a Deliverable

Staging deliverables endpoint

Staging download a deliverable file

Example code.

Additional Endpoints to Test

Retrieve Orders

Retrieve orders by Order ID(s) or Project ID:

https://gpo-staging.broadinstitute.org/api/redoc#tag/Orders-and-Samples/operation/get_orders_api_order_get

Order and Sample Status

Retrieve valid status values for orders and samples:

https://gpo-staging.broadinstitute.org/api/redoc#tag/Catalogs/operation/get_status_catalog_api_catalog_status__entity__get

Available Tests

Retrieve all test codes and definitions available for your project:

https://gpo-staging.broadinstitute.org/api/redoc#tag/Catalogs/operation/get_test_catalog_for_project_api_catalog_project__project_key__tests_get

Launching to Production

Once the testing of the staging endpoints are successfully achieved, onboarding is complete and you may transition to the production environment.

Production Requirements

Before a production project can be initiated:

A Purchase Order (PO) must be provided to your Project Manager
Required consents must be reviewed and approved by the BCL team

Production Setup Steps

Create and Establish a Service Account

This must be a new service account (do not reuse the staging account).

Submit details here: BCL - API Onboarding
Register User Accounts

Submit project and user details here: BCL - Users/Actors
Authenticate Your Production Service Account

What the BCL Team Will Do

Once the above steps are complete, the BCL team will:

Initiate your project in production
Add your service account to the project
Send UI registration invitations to users

A PO is required to create a funding source. Projects cannot be initiated in production without one.

Production Environments

UI: https://bcl-orders.broadinstitute.org/login

API: https://gpo.broadinstitute.org