ENA Credentials

To register studies and samples with the European Nucleotide Archive, SeqDesk authenticates against ENA’s Webin submission service with a single facility-wide account. There is no per-user or per-study credential: one Webin account speaks for the whole instance, so whoever holds facility-admin rights can submit under it.

The screen is Settings → Data Upload in the sidebar; the page itself is headed ENA Configuration (/admin/ena).

Before you start

You need a Webin account from the ENA Webin portal . Its identifier has the form Webin-12345 — the literal prefix Webin- followed by digits only. SeqDesk validates this with ^Webin-\d+$ in two places (on save and on connection test), so a Webin identifier with anything else after the dash is rejected with

ENA username must be in format 'Webin-XXXXX' (e.g., Webin-12345)

The SeqDesk server must also be able to reach wwwdev.ebi.ac.uk and www.ebi.ac.uk over HTTPS. Compute nodes do not need this — only the application host.

Configuring the account

What Test connection does

It is a real submission attempt, not a ping. SeqDesk POSTs to <server>/ena/submit/drop-box/submit/ with HTTP basic auth and a minimal SUBMISSION document whose only action is <VALIDATE/>, alongside a throwaway PROJECT document. Nothing is registered.

A validation failure on the throwaway project still counts as success: the point is that ENA accepted the credentials well enough to validate at all.

Test versus production

Test mode is stored as enaTestMode and defaults to true on a fresh install. Both the settings screen and the study submission flow surface the active server prominently, because a production registration cannot be undone — accessions are permanent even if the record is later suppressed. Validate on the test server first, every time.

Broker accounts

A regular Webin account submits under the affiliation held by ENA for that account. A broker account submits on behalf of other institutes — the usual situation for a service facility handling customer studies — and may set a center_name per submission.

• Turn on Broker account only if ENA has actually granted your Webin account broker permissions.
• With broker mode on, Center name is required. The page refuses to save while it is empty and shows Enter the broker center name before saving.
• The value is written as center_name into the submitted XML for studies and samples. Center names are free text on ENA’s side.
• With broker mode off, no center name is sent and the field is disabled.

Broker mode and center name are stored under ena.brokerAccount and ena.centerName, and can also be supplied through SEQDESK_ENA_BROKER_ACCOUNT and SEQDESK_ENA_CENTER.

Upload readiness

The Upload Readiness panel at the top of the page summarises four checks before anyone tries to submit:

Below it, Submission History lists past registrations with their status (PENDING, PARTIAL, ACCEPTED, ERROR, FAILED) so you can see whether an earlier attempt left work half-finished.

Where the credentials live, and how they are protected

The username, the encrypted password and the test-mode flag are columns on the single site-settings row. GET /api/admin/settings/ena never returns the password — it returns hasPassword and configured booleans only.

Encryption at rest

The Webin password is encrypted before it is written to the database:

Two consequences worth planning for:

• Values stored before encryption was introduced are read as plaintext. Any value without the enc:v1: prefix is passed through unchanged for backwards compatibility, and is upgraded to ciphertext the next time it is saved. If your instance predates this, re-save the password once to encrypt it.
• With no key material at all, saving fails with Cannot encrypt secret: no key material available. Set NEXTAUTH_SECRET (or SEQDESK_ENCRYPTION_KEY) in the environment.

Encryption protects a leaked database dump. It does not protect against someone with both the database and the environment — keep backups and environment files under the same access controls.

Clearing the credentials

Clear credentials appears once an account is configured. It removes the username and password from the instance after a confirmation dialog. Existing accessions on already-submitted studies are unaffected; only future submissions stop working.

Supplying credentials without the UI

The configuration loader accepts:

export SEQDESK_ENA_USERNAME="Webin-12345"
export SEQDESK_ENA_PASSWORD="your-password"
export SEQDESK_ENA_TEST_MODE="true"
export SEQDESK_ENA_CENTER="Your Center Name"
export SEQDESK_ENA_BROKER_ACCOUNT="false"

and the equivalent block in settings.json:

{
  "ena": {
    "username": "Webin-12345",
    "testMode": true,
    "brokerAccount": false,
    "centerName": "Your Center Name"
  }
}

Never commit a Webin password to a config file in version control.

Troubleshooting

See also

• ENA Submission — the researcher-facing submission workflow these credentials enable
• Study Workflow — marking a study ready before registration
• Environment Variables — the full SEQDESK_ENA_* reference