> For the complete documentation index, see [llms.txt](https://help.dragen.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dragen.illumina.com/dragen-v4.6/reference/licensing/api_key_licensing.md).

# BioInsight Platform Licensing

DRAGEN runs licensed through Illumina BioInsight Platform draw on a single BioInsight Credit (BIC) balance, whether DRAGEN runs inside the platform or on infrastructure you manage. Where you run DRAGEN determines only whether you need to provide an API key.

| Where DRAGEN runs                                                   | What you configure                                                                                                                                                                          |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Illumina BioInsight Platform Core, or BaseSpace Sequence Hub (BSSH) | Nothing. The platform licenses each run for you.                                                                                                                                            |
| DRAGEN FPGA Mode on AWS, Bring-Your-Own-License (BYOL)              | A platform API key, provided to DRAGEN at runtime.                                                                                                                                          |
| DRAGEN Software Mode, on your own CPU hardware                      | A platform API key, provided to DRAGEN at runtime.                                                                                                                                          |
| DRAGEN Server (on-prem)                                             | **Not supported.** DRAGEN Server uses licenses installed on the server using a separate prepaid quota. See [DRAGEN Server Licensing](/dragen-v4.6/reference/licensing/onprem_licensing.md). |

If you run DRAGEN only inside Platform Core or BSSH, you do not need an API key, and you can skip [Running DRAGEN on your own infrastructure](#running-dragen-on-your-own-infrastructure) and the sections after it.

{% hint style="info" %}
BYOL runs that authenticate with legacy license credentials (Illumina provided alphanumeric username and password) use a separate prepaid gigabase quota and are documented on [Legacy DRAGEN Cloud Licensing](/dragen-v4.6/reference/licensing/cloud_licensing.md).
{% endhint %}

## Getting access

If you are new to Illumina BioInsight Platform, start with a [free trial](https://help.connected.illumina.com/getting-started). If your organization is already on the platform, your Domain Administrator grants you access and your runs bill to the domain's existing subscription. See [Software Billing](https://help.connected.illumina.com/account-management/software-billing).

## How DRAGEN runs are charged

Your DRAGEN version determines how the DRAGEN licensing charge is calculated. DRAGEN Pricing charges each run based on the type of analysis and its analysis tier.

| Deployment                                          | Pricing on DRAGEN v4.6 and later | Pricing on DRAGEN v4.5 and earlier |
| --------------------------------------------------- | -------------------------------- | ---------------------------------- |
| Illumina BioInsight Platform Core, including BSSH   | DRAGEN Pricing                   | Legacy Gigabase Pricing            |
| DRAGEN Software Mode, on your own CPU hardware BYOL | DRAGEN Pricing                   | Not available                      |
| DRAGEN FPGA Mode on AWS Public Cloud                | DRAGEN Pricing                   | Legacy Gigabase Pricing            |

For both pricing models across every deployment, including legacy license credentials and the DRAGEN Server, see [Licensing by deployment](/dragen-v4.6/reference/licensing.md#licensing-by-deployment).

### Compute and storage in Platform Core

The platform bills these separately from DRAGEN licensing. See the [Platform Core pricing reference](https://help.connected.illumina.com/connected-analytics/reference/r-pricing).

When you run DRAGEN on your own infrastructure, compute and storage are costs of your own cloud account or hardware, and only DRAGEN licensing is charged in BIC.

## Reviewing your usage

All DRAGEN usage licensed through the platform, both in-platform runs and API key runs, is reported in the Illumina BioInsight Platform [Usage Explorer](https://help.connected.illumina.com/account-management/usage-explorer) rather than in DRAGEN output. The price of an individual in-platform analysis is also shown with that analysis in Platform Core.

### Reconciling a run with its charge

On DRAGEN 4.5 and later, each run has a DRAGEN Run UUID. Look up that UUID in the DRAGEN Usage Report in the Usage Explorer to find the exact licensing event for the run.

DRAGEN records the UUID in `.metadata.run_uuid` of the [unified JSON metrics](/dragen-v4.6/product-guides/dragen-v4.6/qc-metrics/json-metrics-reporting.md) file, `<output-prefix>.metrics.json`, in the output directory. DRAGEN 4.6 also prints the UUID to standard output and the run log.

```bash
jq -r '.metadata.run_uuid' <output-directory>/<output-prefix>.metrics.json
```

`dragen_lic` does not report platform usage and rejects API keys with the error in [Troubleshooting](#troubleshooting).

## Running DRAGEN on your own infrastructure

An Illumina BioInsight Platform API key licenses DRAGEN on infrastructure you manage, and charges the same BIC balance as your in-platform runs. It is the recommended path for new BYOL deployments, and it covers two of them:

* **DRAGEN FPGA Mode on AWS BYOL**, on an FPGA-enabled instance in your own cloud account. See [DRAGEN FPGA Mode](/dragen-v4.6/reference/dragen-multi-cloud.md).
* **DRAGEN Software Mode**, on commodity CPU hardware without an FPGA, such as generic cloud instances or High-Performance Computing (HPC) clusters. See [DRAGEN Software Mode](/dragen-v4.6/reference/software-mode.md).

{% hint style="warning" %}
API key licensing is not supported on the on-premises DRAGEN Server. DRAGEN Server runs are licensed with licenses installed on the server and meter against a prepaid gigabase quota, not BIC. See [DRAGEN Server Licensing](/dragen-v4.6/reference/licensing/onprem_licensing.md).
{% endhint %}

### Prerequisites

DRAGEN contacts the license server, `https://license.dragen.illumina.com`, at runtime, so it needs outbound network access to it and cannot run fully offline. DRAGEN FPGA Mode on AWS BYOL also needs access to the instance metadata service, or saved instance identity documents. See [Instance identity](/dragen-v4.6/reference/dragen-multi-cloud/dragen-on-aws.md#instance-identity).

### Illumina BioInsight Platform requirements

A new domain from a [free trial](https://help.connected.illumina.com/getting-started) satisfies the domain requirements for API key licensing, so there is nothing to check or change on the domain.

Existing domains created after August 4, 2026 also satisfy these domain requirements already. For an older domain, confirm both of the following:

* **A private domain.** API key licensing does not work on a public domain, which is the most common reason an otherwise valid setup fails. Older BaseSpace Sequence Hub accounts are the usual case. For more details, see [How to share BaseSpace Sequence Hub data between the public and private domains](https://knowledge.illumina.com/software/basespace-sequence-hub/software-basespace-sequence-hub-reference_material-list/000001666).
* **A qualifying subscription.** Any current Illumina BioInsight Platform subscription (Free Trial, Pay-As-You-Go, or Savings Plan), Platform Core (formerly Illumina Connected Analytics, including the free Platform Core Basic tier), or Illumina Connected Software.

The API key has a requirement of its own, on every domain:

* **Scoped to DRAGEN scopes only.** The key must be scoped, and every scope on it must be a DRAGEN scope. DRAGEN rejects an unscoped key, and it rejects a key that includes any scope other than a DRAGEN scope.

If you are unsure whether your domain qualifies, ask your Domain Administrator, check the [Admin Console](https://help.connected.illumina.com/account-management/admin-console), or contact [Illumina Customer Care](https://www.illumina.com/company/contact-us.html#/customer-care).

## Set up API key licensing

{% stepper %}
{% step %}

## Generate a user API key

Generate a scoped user API key from your Illumina BioInsight Platform domain, and include only DRAGEN scopes on it. See [Generate new API key](https://help.connected.illumina.com/account-management/platform-home#generate-new-api-key).

{% hint style="warning" %}
DRAGEN rejects an unscoped key, and it rejects a key that includes any scope other than a DRAGEN scope, even when a DRAGEN scope is also present. Create a separate key for other platform products.
{% endhint %}

{% hint style="warning" %}
Treat the API key as a secret, because anyone who has it can consume your BIC balance. Prefer the file-based methods below, which keep the key out of command lines, console logs, and scheduler logs, and restrict the file to your own account on shared systems.
{% endhint %}
{% endstep %}

{% step %}

## Provide the API key to DRAGEN

DRAGEN offers multiple methods for providing the API key. Which ones you can use depends on your DRAGEN version:

| Method                                                                  | Key is stored           | DRAGEN version |
| ----------------------------------------------------------------------- | ----------------------- | -------------- |
| `--api-key-file`                                                        | In a file on disk       | 4.6 and later  |
| `DRAGEN_API_KEY_FILE`                                                   | In a file on disk       | 4.6 and later  |
| `DRAGEN_API_KEY_VALUE`                                                  | In the environment only | 4.6 and later  |
| License credentials file, passed with `--lic-credentials`               | In a file on disk       | 4.2 and later  |
| License credentials file, passed with `DRAGEN_LICENSE_CREDENTIALS_FILE` | In a file on disk       | 4.5 and later  |

On DRAGEN 4.2 through 4.5, use a [license credentials file](#license-credentials-file).

### API key file and environment variables

The API key file must contain nothing but a single line with the key. Do not add a label, a key name, or any other content.

{% code title="api\_key.txt" %}

```
<user api key>
```

{% endcode %}

```bash
dragen \
  --api-key-file /path/to/api_key.txt \
  ... # remaining DRAGEN options
```

`DRAGEN_API_KEY_FILE` is equivalent to `--api-key-file`, and `DRAGEN_API_KEY_VALUE` takes the key itself with no file on disk.

```bash
export DRAGEN_API_KEY_FILE=/path/to/api_key.txt
```

```bash
export DRAGEN_API_KEY_VALUE=<user api key>
```

### License credentials file

A license credentials file is the only way to provide an API key on DRAGEN 4.2 through 4.5, and it also works on DRAGEN 4.6. Use the reserved user name `IlluminaPlatform` on the first line, and the API key on the second.

{% code title="credentials.cfg" %}

```
credentials-1=IlluminaPlatform
credentials-2=<user api key>
```

{% endcode %}

Pass the file with `--lic-credentials`, or on DRAGEN 4.5 and later, with the `DRAGEN_LICENSE_CREDENTIALS_FILE` environment variable.

```bash
dragen \
  --lic-credentials /path/to/credentials.cfg \
  ... # remaining DRAGEN options
```

```bash
export DRAGEN_LICENSE_CREDENTIALS_FILE=/path/to/credentials.cfg
```

{% endstep %}
{% endstepper %}

## Preview a charge before running

On DRAGEN 4.6, add `--metering-preview` to an otherwise complete command line. DRAGEN prints the application and analysis tier it estimates for that run, then exits, so nothing is analyzed and nothing is billed. The tier is resolved through Illumina BioInsight Platform, so `--metering-preview` needs the same API key and network access as the run itself.

```bash
dragen \
  --api-key-file /path/to/api_key.txt \
  --metering-preview \
  ... # remaining DRAGEN options
```

```
Application: <application>
Tier: <tier>
<Tier> Features Utilized: <capability>, <capability>
<summary of the estimated charge>
```

The `Features Utilized` line records why a run landed in a given tier, and is the most useful part of the output when you need to reconcile a charge.

## Troubleshooting

| What you see                                                                                                              | What it means                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `To use software mode (--sw-mode), an Illumina Connected API Key must be provided.`                                       | A Software Mode run found no key. It exits before analysis. Provide a key with one of the methods above.                                                                     |
| `ERROR: The --lic-server option is not supported for SW mode.`                                                            | `--lic-server` passes a legacy user name and password, which Software Mode does not accept. It is also deprecated on every deployment, and DRAGEN 4.6 warns when it is used. |
| `ERROR: --metering-preview is only available for Illumina Connected runs, but no Illumina Connected API key was found.`   | [`--metering-preview`](#preview-a-charge-before-running) resolves the tier through the platform, so it needs the same key and network access as the run itself.              |
| `Illumina Connected API Keys are not supported with dragen_lic, please use the Illumina Connected Usage Explorer instead` | `dragen_lic` reports installed prepaid licenses only. See [Reviewing your usage](#reviewing-your-usage).                                                                     |

A run that fails licensing with a valid-looking key is usually a domain problem, or the key is not limited to DRAGEN scopes. Check the [Illumina BioInsight Platform requirements](#illumina-bioinsight-platform-requirements) first, in particular that the domain is private and the key is scoped to DRAGEN scopes only.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.dragen.illumina.com/dragen-v4.6/reference/licensing/api_key_licensing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.