Skip to main content

Authorization

Follow this guide to create a new Illumina BaseSpace credential that will allow Nexla to authenticate to and exchange data with your Illumina BaseSpace Sequence Hub account.
illumina_basespace_api_auth.png

Illumina BaseSpace

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.

Create an Illumina BaseSpace Credential​

  • To create a new Illumina BaseSpace credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

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

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

Access Token​

  1. 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 the Prerequisites section above.

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.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential.

  2. 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.