Illumina BaseSpace

Illumina BaseSpace Sequence Hub is a cloud-based genomics platform that provides secure storage, analysis, and sharing of next-generation sequencing (NGS) data. Integrated directly with Illumina sequencing instruments, BaseSpace Sequence Hub enables research teams and clinical laboratories to manage sequencing runs, launch bioinformatics analysis applications, and collaborate on genomic data—all without requiring a command-line interface or specialized infrastructure. The platform supports a wide range of NGS workflows including RNA-Seq, whole-genome sequencing, exome analysis, amplicon sequencing, de novo assembly, and 16S metagenomics, making it a central hub for genomic data management and analysis at scale.

Power end-to-end data operations for your Illumina BaseSpace API with Nexla. Our bi-directional Illumina BaseSpace connector is purpose-built for Illumina BaseSpace, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Illumina BaseSpace or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Illumina BaseSpace workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

• Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
• Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
• API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
• Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites

To connect Nexla to Illumina BaseSpace Sequence Hub, you will need a BaseSpace access token. The BaseSpace API uses OAuth 2.0 for authentication, and all API requests must include a valid access token that grants Nexla the appropriate level of access to your BaseSpace data.

Access tokens in BaseSpace are scoped to specific permissions and do not expire automatically, making them suitable for long-running integrations. You obtain an access token by registering a developer application in the BaseSpace Developer Portal and completing the OAuth 2.0 authorization flow.

Register as a BaseSpace Developer and Create an Application

Before obtaining an access token, you must register as a developer on the BaseSpace Developer Portal and create an application to receive your OAuth credentials (client_id and client_secret).

1. Navigate to the BaseSpace Developer Portal at developer.basespace.illumina.com/dashboard and sign in using your Illumina BaseSpace account credentials.

2. Click My Apps in the top navigation toolbar to open the application management area.

3. Click the Create New Application button to begin creating a new application.

4. Fill in the application details form:

   • Application Name: Enter a descriptive name for the integration (for example, "Nexla Integration").

   • Application Type: Select the appropriate application type. For server-to-server integrations, select Native or the application type that corresponds to your use case.

   • Description: Optionally provide a description explaining the purpose of the application.

5. Click the Create Application button to save the new application.

6. Once the application is created, navigate to the Credentials tab within the application details page. Record the following values — you will need them to obtain an access token:

   • Client Key (also referred to as client_id)

   • Client Secret (also referred to as client_secret)

Important

The client secret is a sensitive credential. Store it securely and do not share it in code repositories, emails, or other insecure locations. If a secret is ever compromised, return to the BaseSpace Developer Portal and regenerate your application credentials immediately.

Obtain a BaseSpace Access Token

After registering your application and obtaining your client credentials, complete the OAuth 2.0 authorization flow to generate an access token.

BaseSpace supports two OAuth 2.0 authorization flows. For integrations with Nexla, the Device Code Flow is generally the most practical, as it does not require a hosted web server.

Device Code Flow (Recommended for Server-Side Integrations):

1. Make a POST request to the BaseSpace OAuth token endpoint to initiate the device code flow:

   POST https://api.basespace.illumina.com/v1pre3/oauthv2/deviceauthorization

   Include your client_id and the required permission scopes (see BaseSpace Permissions for a full list of available scopes).

2. BaseSpace will return a device_code along with a short verification code and a URI. Open the provided URI in a browser, sign in to your BaseSpace account, and grant the requested permissions.

3. After granting permissions, make a POST request to exchange the device code for an access token:

   POST https://api.basespace.illumina.com/v1pre3/oauthv2/token

   Include your client_id, client_secret, device_code, and grant_type=device_code in the request body.

4. BaseSpace will return an access_token in the response. Copy and store this token securely — it will be used to authenticate all API calls made by Nexla on your behalf.

BaseSpace access tokens do not expire automatically. However, tokens can be revoked at any time from the BaseSpace Developer Portal. For additional details on required permission scopes for your use case, refer to the BaseSpace Permissions documentation.

Required Permissions (Scopes)

When requesting an access token, specify the appropriate scopes based on how Nexla will use the connection:

• READ GLOBAL — Provides read access to your projects, samples, runs, and other BaseSpace resources. Required when using Nexla to ingest data from BaseSpace.

• CREATE GLOBAL — Provides write access to create new projects, samples, and upload files. Required when using Nexla to write data back to BaseSpace.

Request only the minimum scopes required for your integration. Limiting scope follows the principle of least privilege and reduces the impact if a token is ever compromised.

Authenticate

Create a credential in Nexla

1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

3. Enter your Illumina BaseSpace access token in the Access Token field. This token authenticates Nexla with the BaseSpace API and determines what data Nexla can access on your behalf. The access token is the value returned as access_token in the OAuth 2.0 token response when you completed the authorization flow described in Prerequisites.

   Important

   Treat your BaseSpace access token as a sensitive credential equivalent to a password. Do not share it in emails, code repositories, chat applications, or other insecure locations. If you believe a token has been compromised, revoke it immediately from the BaseSpace Developer Portal and generate a replacement.

4. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.

Use as a data source

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Illumina BaseSpace connector tile, then select the credential that will be used to connect to the Illumina BaseSpace instance, and click Next; or, create a new Illumina BaseSpace credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Illumina BaseSpace endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

List Projects

Returns a list of projects for the current authenticated user. Use this endpoint to enumerate all accessible BaseSpace projects for downstream sample and run discovery.

• Sends a GET request to /v1pre3/users/current/projects and returns all projects accessible to the authenticated user.
• Response data is nested under $.Response.Items[*]; each element represents a single project record.

The BaseSpace API uses the authenticated user's access token scope to determine which projects are visible. Ensure your credential has the appropriate read permissions for the projects you intend to ingest.

List Runs

Returns a list of sequencing runs for the current authenticated user. Use this endpoint to track run status, metadata, and quality metrics across your sequencing operations.

• Sends a GET request to /v1pre3/users/current/runs and returns all sequencing runs for the authenticated user.
• Response data is nested under $.Response.Items[*]; each element represents a single run record including status, instrument, and date information.

Run records include metadata such as instrument type, run status, and creation date. These fields are useful for filtering and routing data in downstream Nexla flows.

List Samples

Returns a list of samples for a specific BaseSpace project. Use this endpoint to retrieve sample-level metadata for quality assessment, LIMS integration, or downstream bioinformatics workflows.

• Sends a GET request to /v1pre3/projects/{projectId}/samples and returns all samples within the specified project.
• Response data is nested under $.Response.Items[*]. Configure the following parameters: Project ID — the BaseSpace project ID from which samples will be listed.

Project IDs can be retrieved using the List Projects endpoint. Consider using a Nexla lookup to dynamically pass project IDs into this endpoint for multi-project ingestion workflows.

List Sample Files

Returns a list of files associated with a specific sample. Use this endpoint to enumerate FASTQ files or other sequencing output files for a given sample.

• Sends a GET request to /v1pre3/samples/{sampleId}/files and returns all files associated with the specified sample.
• Response data is nested under $.Response.Items[*]. Configure the following parameters: Sample ID — the BaseSpace sample ID whose files will be listed.

Sample IDs can be retrieved using the List Samples endpoint. File records include download URLs that can be used in downstream processing steps.

List Run Files

Returns a list of files associated with a specific sequencing run. Use this endpoint to retrieve run-level output files such as run logs, InterOp data, and quality metrics.

• Sends a GET request to /v1pre3/runs/{runId}/files and returns all files associated with the specified run.
• Response data is nested under $.Response.Items[*]. Configure the following parameters: Run ID — the BaseSpace run ID whose files will be listed.

Run IDs can be retrieved using the List Runs endpoint. Run files may be large; use file metadata (size, type) returned in the response to filter before initiating any download steps.

List App Sessions

Returns a list of application sessions for the current authenticated user. Use this endpoint to monitor the status of launched BaseSpace applications and analysis pipelines.

• Sends a GET request to /v1pre3/users/current/appsessions and returns all app sessions for the authenticated user.
• Response data is nested under $.Response.Items[*]; each element represents a single app session including its status and associated application details.

App session status values (e.g., Running, Complete, Aborted) can be used to filter records and trigger conditional logic in downstream Nexla flow steps.

List App Results

Returns a list of application results for a specific app session. Use this endpoint to retrieve analysis output metadata produced by BaseSpace applications.

• Sends a GET request to /v1pre3/appsessions/{appSessionId}/appresults and returns all app results for the specified session.
• Response data is nested under $.Response.Items[*]. Configure the following parameters: App Session ID — the BaseSpace app session ID whose results will be listed.

App session IDs can be retrieved using the List App Sessions endpoint. App result records contain references to the output files, which can be retrieved using the List App Result Files endpoint.

List App Result Files

Returns a list of files associated with specific app results. Use this endpoint to enumerate analysis output files generated by BaseSpace applications for downstream processing or archival.

• Sends a GET request to /v1pre3/appresults/{appResultId}/files and returns all files associated with the specified app result.
• Response data is nested under $.Response.Items[*]. Configure the following parameters: App Result ID — the BaseSpace app result ID whose files will be listed.

App result IDs can be retrieved using the List App Results endpoint. File records include pre-signed download URLs valid for a limited time period.

Cross-resource search across samples, runs, projects, genomes

Performs a cross-resource search across samples, runs, projects, genomes, app results, and files using a query string. Use this endpoint to discover resources across multiple BaseSpace entity types in a single call.

• Sends a GET request to /v1pre3/search with scope, query, and offset parameters. Response data is nested under $.Response.Items[*].
• Configure the following parameters: Scope — the resource type to search (e.g., Projects, Samples, Runs); Query — the search string; Offset — starting position for paginated results.

Use the Scope parameter to narrow search results to specific resource types. Combining this endpoint with the Offset parameter allows paginated retrieval of large search result sets.

Retrieve File Metadata and Download URL

Retrieves metadata and a pre-signed download URL for a single file. Use this endpoint to obtain time-limited download URLs for specific BaseSpace files.

• Sends a GET request to /v1pre3/files/{fileId} and returns metadata and a pre-signed download URL for the specified file.
• Response data is returned at the root path $. Configure the following parameters: File ID — the BaseSpace file ID for which to retrieve metadata and a download URL.

Pre-signed download URLs returned by this endpoint are time-limited. Retrieve and use them promptly within your data flow to avoid expiration errors.

List Reference Genomes

Lists reference genomes available in BaseSpace, including build, organism, and other metadata. Use this endpoint to retrieve genome reference data for annotation or pipeline configuration workflows.

• Sends a GET request to /v1pre3/genomes with optional sort parameters. Response data is nested under $.Response.Items[*].
• Configure the following parameters: Sort By — the field to sort results by; Sort Direction — ascending or descending sort order.

Genome records include organism name, build identifier, and species information. This endpoint is useful for populating reference lookup tables used in other BaseSpace data flows.

Retrieve Single Project by ID

Retrieves a single project by its BaseSpace project ID. Use this endpoint when you need complete metadata for a specific project rather than a full list.

• Sends a GET request to /v1pre3/projects/{projectId} and returns the full project record.
• Response data is returned at the root path $. Configure the following parameters: Project ID — the BaseSpace project ID to retrieve.

This endpoint returns a single object rather than an array. Use $ as the path to data rather than $.Response.Items[*] when configuring this endpoint.

List App Results Under a Project

Lists all app results directly under a project, without going through app sessions. Use this endpoint to retrieve analysis outputs at the project level for project-wide reporting.

• Sends a GET request to /v1pre3/projects/{projectId}/appresults and returns app results for the specified project. Response data is nested under $.Response.Items[*].
• Configure the following parameters: Project ID — the BaseSpace project ID; Sort By — optional sort field; Sort Direction — optional sort order; Offset — starting position for paginated results.

Use the Offset parameter to paginate through large numbers of app results within a project. The Sort By and Sort Direction parameters allow you to retrieve the most recent results first.

Retrieve Single Run by ID

Retrieves a single sequencing run by its BaseSpace run ID. Use this endpoint to fetch complete run metadata for a specific run.

• Sends a GET request to /v1pre3/runs/{runId} and returns the full run record.
• Response data is returned at the root path $. Configure the following parameters: Run ID — the BaseSpace run ID to retrieve.

This endpoint returns a single object. Use $ as the path to data. Run IDs can be retrieved from the List Runs endpoint.

Retrieve Single Sample by ID

Retrieves a single sample by its BaseSpace sample ID. Use this endpoint when you need complete metadata for a specific sample.

• Sends a GET request to /v1pre3/samples/{sampleId} and returns the full sample record.
• Response data is returned at the root path $. Configure the following parameters: Sample ID — the BaseSpace sample ID to retrieve.

This endpoint returns a single object. Use $ as the path to data. Sample IDs can be retrieved from the List Samples endpoint.

Retrieve Current User Profile

Retrieves the currently authenticated user's profile and permission scope. Use this endpoint to validate credentials, inspect access scopes, or retrieve the current user ID for use in other API calls.

• Sends a GET request to /v1pre3/users/current and returns the authenticated user's profile information.
• Response data is returned at the root path $. No additional parameters are required.

This endpoint is useful for verifying that your BaseSpace credential is correctly configured and has the expected permission scopes before building more complex data flows.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration

Illumina BaseSpace sources can also be manually configured to ingest data from any valid BaseSpace API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

The BaseSpace API is available at two base URLs: Version 1 (v1pre3) at https://api.basespace.illumina.com/v1pre3/ and Version 2 at https://api.basespace.illumina.com/v2/. Common endpoints include https://api.basespace.illumina.com/v2/projects, https://api.basespace.illumina.com/v2/runs, https://api.basespace.illumina.com/v2/biosamples, https://api.basespace.illumina.com/v2/datasets, and https://api.basespace.illumina.com/v1pre3/users/current/projects. For a complete list of available endpoints and parameters, refer to the BaseSpace V2 API Reference and BaseSpace V1 API Reference.

BaseSpace API responses consistently wrap the relevant data records inside an Items array within a Response object, so for most BaseSpace endpoints the path to data is $.Response.Items[*] and the path to metadata (such as TotalCount) is $.Response. Endpoints that return a single object rather than a list use $ as the path to data instead. You do not need to include the x-access-token authentication header — Nexla automatically includes your BaseSpace access token from the configured credential with every API request.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Illumina BaseSpace data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination

Click the + icon on the Nexset that will be sent to the Illumina BaseSpace destination, and select the Send to Destination option from the menu. Select the Illumina BaseSpace connector from the list of available destination connectors, then select the credential that will be used to connect to the Illumina BaseSpace instance, and click Next; or, create a new Illumina BaseSpace credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Illumina BaseSpace endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

Upload File to AppResult

Uploads a file into an existing AppResult using multi-part or single-part file upload. Use this endpoint to write analysis output files back to BaseSpace after processing in Nexla.

• Sends a POST request to /v1pre3/appresults/{appResultId}/files with the file content as the request body.
• Configure the following parameters: AppResult ID — the BaseSpace app result ID into which the file will be uploaded.

The access token must have write scopes (e.g., CREATE GLOBAL) to upload files. Read-only tokens will be rejected by the BaseSpace API.

Create AppResult Under a Project

Creates a new AppResult under a project — the primary mechanism for writing analysis outputs back to BaseSpace. Use this endpoint to register analysis results in BaseSpace from external pipelines.

• Sends a POST request to /v1pre3/projects/{projectId}/appresults with a JSON payload describing the new app result.
• Configure the following parameters: Project ID — the BaseSpace project ID under which the new AppResult will be created.

Creating an AppResult requires an active AppSession. Ensure the associated AppSession is in an active state before writing results. Use the Update AppSession Status endpoint to mark the session complete after all results are written.

Update AppSession Status

Updates an AppSession status (e.g., mark Complete or Aborted) to signal end-of-analysis. Use this endpoint to close out analysis sessions after all results and files have been written to BaseSpace.

• Sends a POST or PATCH request to /v1pre3/appsessions/{appSessionId} with the new status value in the request body.
• Configure the following parameters: AppSession ID — the BaseSpace app session ID whose status will be updated.

Status transitions are one-way; a session marked Complete or Aborted cannot be re-opened. Confirm all results are successfully written before setting the terminal status.

Create Project

Creates a new project to organize samples and app results. Use this endpoint to programmatically provision BaseSpace projects from external sample management or LIMS systems.

• Sends a POST request to /v2/projects (or /v1pre3/projects) with a JSON payload containing the project name and optional description.
• No path parameters are required for project creation; all project fields are provided in the request body.

Newly created projects are associated with the authenticated user's account. Ensure your credential has the CREATE GLOBAL scope to create projects in BaseSpace.

Once the selected endpoint template has been configured, Nexla can send a test payload to the Illumina BaseSpace API to ensure that the destination is configured correctly. Click the Test button to the right of the endpoint selection menu, and check the sample data in the Endpoint Test Result panel on the right to verify the destination is configured correctly before saving.

Manual configuration

Illumina BaseSpace destinations can also be manually configured to write data to any valid BaseSpace API endpoint that supports data creation or updates. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

Common BaseSpace write endpoints include POST https://api.basespace.illumina.com/v2/projects (create a new project) and POST https://api.basespace.illumina.com/v2/datasets (create a new dataset within a project). The BaseSpace API expects data in JSON format for most write operations — refer to the BaseSpace V2 API Reference for the specific request body schema required by each endpoint.

The access token configured in your credential must have the appropriate write scopes (e.g., CREATE GLOBAL) to perform write operations against the BaseSpace API — read-only tokens will not be able to create or modify resources. You do not need to include the x-access-token authentication header or the Content-Type: application/json header — Nexla adds these automatically based on your credential and selected data format.

Save & activate

Once all endpoint settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Illumina BaseSpace destination. Nexla will now begin delivering data to the configured BaseSpace endpoint according to the settings configured above.