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
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.
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:
Contact
annotation_support@illumina.comfor a professional (premium) credentials file.Use your on‑premise DRAGEN serial number (entitles premium access).
Use BYOL (Bring Your Own License) credentials (cloud legacy deployments).
Use a DRAGEN API key (cloud/platform deployments).
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):
Explicit command line arguments (
--credentials-file,--lic-credentials,--api-key-file)Environment variables
Default credentials directory:
~/.ilmnAnnotations/
Supported File Formats
1. credentials.json (Recommended, supports all methods)
Example minimal variants:
All fields (only supply the ones you use):
2. dragen_api_key.txt
Plain text containing only the DRAGEN API key value:
3. dragen_credentials.txt (license credentials key-value pairs)
4. premium.lic (Autogenerated)
Downloaded automatically next to credentials.json containing encoded access information for premium sources.
Environment Variables (Optional)
You can set these to avoid passing files:
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):
Convert existing BYOL dragen_credentials.txt file to JSON:
Add MyIllumina key alongside another method:
Command Line Options
--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:
Annotate with Licensed Content
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:
Refresh
premium.lic(online run) or renew entitlement.Verify credential file format & location.
Re-run DataManager to sync versions.
Last updated
Was this helpful?

