Most HPC systems no longer accept an SSH key on its own. Logging in to a cluster usually also asks for a password, a one-time code or a Duo push. This multi-factor authentication is designed to need a person. Tools that reach the cluster for you, such as job submitters, file transfer clients and workflow engines, either have to stop and wait for that person or can't be used at all.
Airavata supports both. Runs remain an automated workflow (stage in, submit, monitor, stage out), and when a cluster asks for a second factor, Airavata pauses that login, asks you for the answer, and then continues. You answer once per login, not once per command. Everything else in the run is automated.
Interactive authentication is a property of an SSH credential. A credential has an SSH key pair and one flag:
| Field | Meaning |
|---|---|
privateKey, publicKey, passphrase | The key pair. Airavata always offers it first. |
password | Optional, write-only. Answers the host's first lone password prompt, so you are not asked for it. Ignored unless fullInteractive. |
fullInteractive | true if the host also asks keyboard-interactive questions (password, OTP, Duo) after the key. Default false. |
In the dashboard, this is the checkbox “Host also asks keyboard-interactive questions (password, OTP, Duo) — answer them from this dashboard” when you register a credential.
A credential is not used on its own. It is attached to whatever logs in to a host:
SSH credential (fullInteractive) ──▶ Cluster config ──▶ runs: job submission, monitoring, staging
──▶ Data storage ──▶ data product upload/download, staging
──▶ (direct use) ──▶ partition discovery, allocation discovery
Any login that uses a fullInteractive credential can raise an interactive auth. The prompt goes to the user whose action caused the login:
| Login caused by | Prompt goes to |
|---|---|
| A run (staging, submission, monitoring) | the owner of the process |
| Uploading or downloading data product content | the user making the request |
| Partition or allocation discovery | the user making the request |
This affects shared cluster configs and storages. If you share a config that uses an interactive credential, a teammate who launches a run under it is the one asked for the password and second factor. Share an interactive login only with people who can answer its prompts.
When the login starts, Airavata:
If the host asks again, for example a Duo prompt after the password, that is a new interactive auth with a new id. A stored password answers the first password prompt itself; every other prompt, such as a Duo passcode, still goes to the user.
An authenticated connection is kept and reused by every operation that logs in with the same host, login user and credential on behalf of the same user. For one run, that covers stage-in, submission, monitoring and stage-out. You answer once, and the steps that follow use the same connection. The connection is closed after five minutes without use, and the next login asks again.
{ "authId": "00000000-0000-4000-8000-000000000001", "hostName": "login.cluster.example.edu", "port": 22, "loginUser": "jdoe", "sshCredentialId": "00000000-0000-4000-8000-000000000002", "banner": "\nExample HPC Cluster\n\nLogin with your password + Duo multi-factor.\n", "name": "", "instruction": "", "prompts": [ { "text": "Password: ", "echo": false } ], "createdAt": "2026-10-30T14:02:11.482Z" }
| Field | Meaning |
|---|---|
hostName, port, loginUser, sshCredentialId | Which login is waiting. Show these so you know what you are answering. |
banner | The host's pre-login message, as a terminal would print it. |
name, instruction | Any heading the host sent with the prompts. |
prompts[] | The questions. echo: false means the answer is secret (a password or OTP) and should be masked. |
The answer is one response per prompt, in order: {"responses": ["<password>"]}. You can instead send {"cancel": true} to fail the login immediately rather than leave it waiting.
Answers go straight to the SSH handshake. They are not logged or stored. A credential's password is stored, write-only, and never returned; see api.md.
An auth exists only while its login is waiting. It disappears once it is answered or the login gives up. Only the user it was raised for can see or answer it. Admins cannot see other users' auths either.
A run doesn't need you to be watching the moment it starts. If a prompt is not answered before the login gives up, that step fails like any other failed connection. It is retried according to its retry settings (staging steps retry up to three times, and each retry can raise a new prompt). If the run still fails, retry the process:
curl -s -X POST localhost:9095/api/v1/processes/"$PROCESS_ID"/retry \ -H "Authorization: Bearer $TOKEN"
A retry continues from the step that failed. Steps that already completed are skipped, inputs that were already staged are not copied again, and a submitted job is never submitted twice. The retry raises a new prompt, which you answer, and the run carries on. The dashboard's process view has the same retry action. See Retry a Process.
Partition and allocation discovery work the same way, but the request itself waits for up to five minutes for you to answer. If no answer arrives in time, run the discovery again.
The dashboard keeps a live connection open for you. When any of your logins is waiting:
Click Later to hide a prompt until another one arrives. The login keeps waiting, and the badge still shows it.
Keeping a dashboard tab open while runs are active is the simplest way to make sure prompts are answered on time.
Clients that want to be notified as soon as a prompt appears should subscribe:
GET /api/v1/ssh-interactive-auths/ws
The socket sends your oldest waiting auth as a challenge, or idle when nothing is waiting. When that auth is answered, here or anywhere else, or abandoned, it sends the next one.
◀ {"type":"challenge","auth":{"authId":"3f2c…","prompts":[{"text":"Password: ","echo":false}], …}}
▶ {"authId":"3f2c…","responses":["<password>"]}
◀ {"type":"accepted","authId":"3f2c…"}
◀ {"type":"challenge","auth":{"authId":"9a1b…","prompts":[{"text":"Duo passcode: ","echo":true}], …}}
▶ {"authId":"9a1b…","responses":["<passcode>"]}
◀ {"type":"accepted","authId":"9a1b…"}
◀ {"type":"idle"}
Authentication works as it does for any other route. Send Authorization: Bearer $TOKEN on the upgrade request. A browser, which cannot set that header, offers the token as a subprotocol instead (base64url.bearer.<token> alongside airavata.v1).
websocat -H="Authorization: Bearer $TOKEN" "ws://localhost:9095/api/v1/ssh-interactive-auths/ws"
To answer one specific auth, use GET /api/v1/ssh-interactive-auths/{authId}/ws. It sends that auth's challenge, accepts one answer and closes.
For clients that can't keep a socket open:
GET /api/v1/ssh-interactive-auths # your waiting logins, oldest first
GET /api/v1/ssh-interactive-auths/{authId} # one of them
POST /api/v1/ssh-interactive-auths/{authId}/response # {"responses": [...]} or {"cancel": true}
204 means Airavata passed the answer to the host. It does not mean the host accepted it. A wrong password shows up as the step failing, or as a new prompt if the host asks again. With REST you have to poll the list to find out when a prompt appears, which is why the WebSocket or the dashboard works better for runs.
Full request, response and error details are in api.md.
The Airavata MCP server supports interactive auth already. When a run, discovery or transfer is waiting on a prompt, the assistant tells you to answer it in a terminal:
airavata-mcp ssh-auth
This command shows each waiting login and reads secret answers without echoing them. Passwords and codes are never typed into the AI conversation, and the assistant is instructed never to ask for them there.
fullInteractive: true. Install its public key for your account on the host as usual. Airavata still offers the key first.airavata-mcp ssh-auth, whenever you launch runs, discover partitions or allocations, or move data through that login.If a host needs only a key, leave fullInteractive off. Logins then never wait on a person, and runs are fully unattended.