> For the complete documentation index, see [llms.txt](https://help.connected.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.connected.illumina.com/annotation/v3.27/introduction/licensedcontent.md).

# Licensed Content

Illumina Connected Annotations supports the following premium (licensed) content available through an Illumina license. A valid license/credentials allow downloading and annotating with these data sources:

* COSMIC
* OMIM
* PrimateAI-3D
* SpliceAI
* PromoterAI

{% hint style="info" %}
A license may be customized to allow access to one or more of the above at the time of license creation.
{% endhint %}

{% hint style="info" %}
DRAGEN bundles Illumina Connected Annotations. When run **inside DRAGEN**, all premium content is available (assuming your DRAGEN entitlement is current). This does **not** automatically grant access when running the standalone tools outside DRAGEN; you still need proper credentials (serial number, API key, or BYOL credentials).
{% endhint %}

### Overview of Licensing / Authentication Methods

The annotation tools support multiple authentication paths. You only need **one**. If multiple are present, a priority order is applied.

| Method                              | Typical Environment          | What You Provide                    |
| ----------------------------------- | ---------------------------- | ----------------------------------- |
| DRAGEN Serial Number                | On‑premise DRAGEN server     | Serial number (automatic or manual) |
| BYOL Credentials (ApiKey/ApiSecret) | Cloud / legacy BYOL          | User ID + Password                  |
| DRAGEN API Key                      | Cloud / platform deployments | API key value or file               |
| MyIllumina API Key                  | Base access (non‑premium)    | MyIllumina API key                  |

### How to Obtain Credentials / License

You can obtain credentials in any of these ways:

1. Contact `annotation_support@illumina.com` for a professional (premium) credentials file.
2. Use your on‑premise DRAGEN serial number (entitles premium access).
3. Use BYOL (Bring Your Own License) credentials (cloud legacy deployments).
4. Use a DRAGEN API key (cloud/platform deployments).
5. Use a MyIllumina API key for basic (non‑premium) access.

Visit [Illumina Connected Annotations](https://developer.illumina.com/illumina-connected-annotations) for more details.

### Credentials Discovery Locations

DataManager and Nirvana automatically look in these locations (in order):

1. Explicit command line arguments (`--credentials-file`, `--lic-credentials`, `--api-key-file`)
2. Environment variables
3. Default credentials directory: `~/.ilmnAnnotations/`

### Supported File Formats

#### 1. credentials.json (Recommended, supports all methods)

Example minimal variants:

```json
{ "DragenSerialNo": "<your-serial-number>" }
```

```json
{ "ApiKey": "<user-id>", "ApiSecret": "<password>" }
```

```json
{ "MyIlluminaApiKey": "<myillumina-api-key>" }
```

All fields (only supply the ones you use):

```json
{
  "MyIlluminaApiKey": "<optional-myillumina-key>",
  "DragenSerialNo": "<optional-serial-number>",
  "ApiKey": "<optional-byol-user-id>",
  "ApiSecret": "<optional-byol-password>",
  "DragenApiKey": "<optional-dragen-api-key>"
}
```

#### 2. dragen\_api\_key.txt

Plain text containing only the DRAGEN API key value:

```
your-dragen-api-key-value
```

#### 3. dragen\_credentials.txt (license credentials key-value pairs)

```
credentials-1=<user-id>
credentials-2=<password>
```

#### 4. premium.lic (Autogenerated)

Downloaded automatically next to `credentials.json` containing encoded access information for premium sources.

{% hint style="info" %}
**Refreshing premium.lic**

If you see licensing errors, delete `premium.lic`. The next run of DataManager or Nirvana (with internet access) will regenerate it.
{% endhint %}

### Environment Variables (Optional)

You can set these to avoid passing files:

| Variable                          | Purpose                     |
| --------------------------------- | --------------------------- |
| `MY_ILLUMINA_API_KEY`             | MyIllumina API key          |
| `DRAGEN_SERIAL_NUMBER`            | DRAGEN serial number        |
| `DRAGEN_API_KEY_VALUE`            | DRAGEN API key value        |
| `DRAGEN_API_KEY_FILE`             | Path to API key file        |
| `NIRVANA_API_KEY`                 | BYOL user id                |
| `NIRVANA_API_SECRET`              | BYOL password               |
| `DRAGEN_LICENSE_CREDENTIALS_FILE` | Path to BYOL key-value file |

### Creating credentials.json Automatically (Examples)

On‑premise DRAGEN (serial number):

```bash
cat > ~/.ilmnAnnotations/credentials.json << EOF
{ "DragenSerialNo": "$(dragen_info -qs)" }
EOF
```

Convert existing BYOL `dragen_credentials.txt` file to JSON:

```bash
cat > ~/.ilmnAnnotations/credentials.json << EOF
{
  "ApiKey": "$(awk -F' = ' '/^credentials-1/ {print $2}' ~/dragen_credentials.txt)",
  "ApiSecret": "$(awk -F' = ' '/^credentials-2/ {print $2}' ~/dragen_credentials.txt)"
}
EOF
```

Add MyIllumina key alongside another method:

```bash
jq '. + {"MyIlluminaApiKey":"<your-myillumina-key>"}' ~/.ilmnAnnotations/credentials.json > ~/.ilmnAnnotations/credentials.tmp && mv ~/.ilmnAnnotations/credentials.tmp ~/.ilmnAnnotations/credentials.json
```

### Command Line Options

| Option                          | Purpose                              |
| ------------------------------- | ------------------------------------ |
| `--credentials-file, -l <path>` | Path to `credentials.json`           |
| `--lic-credentials <path>`      | Path to BYOL key-value file          |
| `--api-key-file <path>`         | Path to raw DRAGEN API key text file |
| `-l, --credentials-file <path>` | Path to `credentials.json`           |

### Offline Mode

Premium content access is validated online in the background. For **offline runs**, ensure the auto-downloaded `premium.lic` sits beside the active `credentials.json`. The file expires after \~90 days; refresh by:

* Running DataManager (any download/sync) with internet
* Running Nirvana with internet

### Re-downloading premium.lic

Just re-run a download command (even a metadata refresh) or any Nirvana annotation with connectivity; a new file will replace the old.

### Download Licensed Content

See: [DataManager](/annotation/v3.27/utilities/data-manager.md) — always include credentials via one of the supported methods.

Example:

```bash
dotnet DataManager.dll download \
  -r GRCh38 \
  --credentials-file ~/.ilmnAnnotations/credentials.json \
  --dir /data/nirvana_data \
  --versions-config /opt/dragen/<DRAGEN_VERSION>/resources/annotation/all_annotations_GRCh38.json
```

### Annotate with Licensed Content

```bash
dotnet Annotator.dll \
  --ref ~/data/References/Homo_sapiens.GRCh38.Nirvana.dat \
  --sd ~/data/SupplementaryAnnotation/GRCh38 \
  -c ~/data/Cache \
  -i ~/input.vcf.gz \
  -o ~/output \
  --credentials-file ~/.ilmnAnnotations/credentials.json \
  --versions-config /opt/dragen/<DRAGEN_VERSION>/resources/annotation/all_annotations_GRCh38.json
```

### Licensing Errors

If the license expires, annotation stops with an error code. You may bypass with `--ignoreLicenseError` (or equivalent flag) — only basic (non‑premium) sources will then be annotated. Recommended next steps:

1. Refresh `premium.lic` (online run) or renew entitlement.
2. Verify credential file format & location.
3. Re-run DataManager to sync versions.

{% hint style="warning" %}
Bypassing licensing errors means premium data (COSMIC, OMIM, PrimateAI‑3D, SpliceAI) will be absent from results.
{% endhint %}


---

# 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.connected.illumina.com/annotation/v3.27/introduction/licensedcontent.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.