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
• Primate AI-3D
• Splice AI
• Promoter AI

tip

A license may be customized to allow access to one or more of the above at the time of license creation.

note

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

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 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:

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

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

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

All fields (only supply the ones you use):

{
  "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.

Refreshing premium.lic

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

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):

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

Convert existing BYOL dragen_credentials.txt file to JSON:

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:

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 — always include credentials via one of the supported methods.

Example:

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

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.

caution

Bypassing licensing errors means premium data (COSMIC, OMIM, Primate AI‑3D, Splice AI) will be absent from results.